@djvlc/runtime-core 1.1.1 → 1.1.2

package/dist/index.d.ts

@@ -1,81 +1,176 @@
 import * as _djvlc_contracts_types from '@djvlc/contracts-types';
-import { PageResolveResponse, ActionResult, ExpressionContext, Expression, ExpressionValidationResult, ActionRef, EventHandler, 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';
+import { PageResolveResponse, ActionResult, ExpressionContext, Expression, ExpressionValidationResult, ActionRef, EventHandler, HostApi, NavigateOptions, TrackEvent as TrackEvent$1, DialogOptions, DialogResult, ToastOptions, ClipboardApi, StorageApi, ShareOptions, ShareResult, ConfirmOptions, ActionSheetOptions, ActionSheetResult, PreviewImageOptions, ScanCodeResult, ComponentContext, ErrorCode, ManifestItem, PageManifest, PageSchema, CapabilityName, 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';
 
 /**
- * User API 适配器接口
- * 统一 Runtime 与 User API 的交互：页面解析、动作执行、数据查询、埋点
- * 认证、请求头、重试等逻辑由实现类统一处理，便于测试与切换实现（如 openapi-user-client）
+ * User API Adapter（端口接口）
+ *
+ * runtime-core 只定义 Port 接口，不绑定任何 HTTP 客户端或鉴权实现。
+ * 由宿主注入实现（如 @djvlc/runtime-client-sdk 的 OpenApiUserAdapter）。
+ *
+ * 注意：此接口以 runtime domain 为中心，不暴露 OpenAPI Request/Response 类型。
  */
 
-/** 页面解析入参 */
+/**
+ * 页面解析参数
+ */
 interface ResolvePageParams {
+    /** 页面 ID */
     pageId: string;
+    /** 用户 ID */
     uid?: string;
+    /** 设备 ID */
     deviceId?: string;
+    /** 环境 */
     env?: 'preview' | 'staging' | 'prod';
+    /** 渠道 */
     channel?: string;
+    /** 预览 Token */
     previewToken?: string;
 }
-/** 动作执行入参 */
+/**
+ * 动作执行参数
+ */
 interface ExecuteActionParams {
+    /** 动作类型 */
     actionType: string;
+    /** 动作参数 */
     params: Record<string, unknown>;
+    /** 上下文 */
     context: {
         pageVersionId: string;
         uid?: string;
         deviceId?: string;
         channel?: string;
-        appId: string;
+        appId?: string;
     };
-    idempotencyKey: string;
+    /** 幂等键 */
+    idempotencyKey?: string;
 }
-/** 数据查询入参 */
+/**
+ * 查询执行参数
+ */
 interface ExecuteQueryParams {
+    /** 查询版本 ID */
     queryVersionId: string;
-    params?: Record<string, unknown>;
+    /** 查询参数 */
+    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;
+    /** 事件类型 */
+    type?: 'page_view' | 'click' | 'exposure' | 'custom';
+    /** 时间戳 */
     timestamp?: number;
+    /** 上下文 */
     context: {
         pageVersionId: string;
-        runtimeVersion: string;
+        runtimeVersion?: string;
         userId?: string;
         deviceId?: string;
         channel?: string;
-        appId: string;
-        env: string;
+        appId?: string;
+        env?: string;
     };
 }
 /**
- * User API 适配器
- * 只约定入参/出参，不绑定具体 HTTP 库；由 Runtime 注入实现，单测可注入 Mock
+ * User API 适配器接口
+ *
+ * 统一 runtime 对 User API 的调用，所有请求头、鉴权、重试等逻辑由实现方处理。
+ * runtime-core 不绑定任何具体 HTTP 客户端。
  */
 interface UserApiAdapter {
-    /** 页面解析 GET /page/resolve */
+    /**
+     * 解析页面
+     * @param params 解析参数
+     * @returns 页面解析响应
+     */
+    resolvePage(params: ResolvePageParams): Promise<PageResolveResponse>;
+    /**
+     * 执行动作
+     * @param params 动作参数
+     * @returns 动作结果
+     */
+    executeAction<T = unknown>(params: ExecuteActionParams): Promise<ActionResult<T>>;
+    /**
+     * 执行查询
+     * @param params 查询参数
+     * @returns 查询结果
+     */
+    executeQuery(params: ExecuteQueryParams): Promise<ExecuteQueryResult>;
+    /**
+     * 埋点上报
+     * @param payload 埋点数据
+     */
+    track(payload: TrackPayload): void;
+}
+/**
+ * Mock 适配器配置
+ */
+interface MockUserApiAdapterOptions {
+    /** 模拟延迟（毫秒） */
+    delay?: number;
+    /** 模拟页面数据（兼容旧字段名） */
+    mockPage?: PageResolveResponse;
+    /** 页面解析响应（推荐使用） */
+    resolvePageResponse?: PageResolveResponse;
+    /** 解析页面时抛出的错误 */
+    resolvePageThrow?: Error;
+    /** 模拟动作结果 */
+    mockActionResult?: <T>() => ActionResult<T>;
+    /** 模拟查询结果 */
+    mockQueryResult?: () => ExecuteQueryResult;
+}
+/**
+ * 调用记录
+ */
+interface MockUserApiAdapterCalls {
+    resolvePage: ResolvePageParams[];
+    executeAction: ExecuteActionParams[];
+    executeQuery: ExecuteQueryParams[];
+    track: TrackPayload[];
+}
+/**
+ * Mock User API 适配器
+ * 用于单元测试和开发环境
+ */
+declare class MockUserApiAdapter implements UserApiAdapter {
+    private options;
+    /** 调用记录 */
+    calls: MockUserApiAdapterCalls;
+    constructor(options?: MockUserApiAdapterOptions);
     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;
+    private delay;
+    /** 重置调用记录 */
+    resetCalls(): void;
 }
 
 /**
@@ -919,44 +1014,6 @@ declare class ActionBridge {
     private log;
 }
 
-/**
- * 测试用 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 定义
@@ -1013,7 +1070,7 @@ declare class HostAPIImpl implements HostApi {
     private loadingElement;
     constructor(options: HostAPIOptions);
     navigate(options: NavigateOptions): Promise<void>;
-    track(event: TrackEvent): void;
+    track(event: TrackEvent$1): void;
     requestData<T = unknown>(queryId: string, params?: Record<string, unknown>): Promise<T>;
     executeAction<T = unknown>(actionType: string, params?: Record<string, unknown>): Promise<ActionResult<T>>;
     openDialog(options: DialogOptions): Promise<DialogResult>;
@@ -1084,6 +1141,14 @@ declare class DjvlcRuntime {
      * 初始化运行时
      */
     init(): Promise<void>;
+    /**
+     * 从已解析的页面结果加载（供 SDK resolve 后注入，跳过 API + CDN 请求）
+     */
+    loadFromResolved(page: PageResolveResult): Promise<PageResolveResult>;
+    /**
+     * 注入预取数据到 dataStore（query 缓存），供 SDK applyPrefetch 使用
+     */
+    setPrefetchedData(data: Record<string, unknown>): void;
     /**
      * 加载页面
      */
@@ -1476,6 +1541,229 @@ declare class AssetLoader {
     loadScript(url: string, integrity?: string): Promise<void>;
 }
 
+/** Tenant 解析入参 */
+interface ResolveTenantInput {
+    /** 请求 Host */
+    host?: string;
+    /** 请求路径 */
+    path?: string;
+    /** 额外请求头 */
+    headers?: Record<string, string>;
+}
+/** Tenant 解析结果 */
+interface ResolveTenantResult {
+    /** 租户 ID */
+    tenantId: string;
+    /** 租户配置 */
+    config: unknown;
+}
+/** Tenant 端口 */
+interface TenantPort {
+    resolveTenant(input: ResolveTenantInput): Promise<ResolveTenantResult>;
+}
+/** 客户端信息 */
+interface ClientInfo {
+    /** User Agent */
+    ua?: string;
+    /** IP 地址 */
+    ip?: string;
+    /** 设备 ID */
+    deviceId?: string;
+}
+/** 认证信息 */
+interface AuthInfo {
+    /** Token（runtime 只关心有没有 token，怎么塞 header 由 adapter 决定） */
+    token?: string;
+}
+/** 追踪信息 */
+interface TraceInfo {
+    /** Trace ID */
+    traceId?: string;
+    /** Span ID */
+    spanId?: string;
+}
+/** Page 解析入参（以 runtime 需要为准） */
+interface ResolvePageInput {
+    /** 租户 ID */
+    tenantId?: string;
+    /** 页面 ID */
+    pageId: string;
+    /** 页面版本 ID（支持灰度/回滚/复现） */
+    pageVersionId?: string;
+    /** 语言 */
+    locale?: string;
+    /** 用户 ID */
+    uid?: string;
+    /** 客户端信息 */
+    client?: ClientInfo;
+    /** 认证信息 */
+    auth?: AuthInfo;
+    /** 追踪信息 */
+    trace?: TraceInfo;
+    /** 超时（毫秒） */
+    timeoutMs?: number;
+    /** AbortSignal */
+    signal?: AbortSignal;
+}
+/** 缓存状态 */
+type CacheStatus = 'HIT' | 'MISS' | 'BYPASS';
+/** Page 解析结果元数据 */
+interface ResolvePageMeta {
+    /** 缓存状态 */
+    cache: CacheStatus;
+    /** 解析时间戳 */
+    resolvedAt: number;
+    /** ETag */
+    etag?: string;
+    /** 缓存 TTL（秒） */
+    cacheTtlSeconds?: number;
+}
+/** Page 解析结果（含 schema 与可选预取数据） */
+interface ResolvePageResult {
+    /** 页面版本 ID */
+    pageVersionId: string;
+    /** 页面 Schema（严格类型） */
+    page: PageSchema;
+    /** 预取数据，可注入 runtime 的 dataStore（query 缓存） */
+    prefetchedData?: Record<string, unknown>;
+    /** 元数据 */
+    meta: ResolvePageMeta;
+    /** 完整页面解析结果，供 runtime.loadFromResolved() 使用 */
+    pageResolveResult?: PageResolveResult;
+}
+/** Page Runtime 端口（核心） */
+interface PageRuntimePort {
+    resolvePage(input: ResolvePageInput): Promise<ResolvePageResult>;
+}
+
+/** Data 查询入参 */
+interface DataQueryInput {
+    /** 租户 ID */
+    tenantId?: string;
+    /** 查询版本 ID */
+    queryVersionId: string;
+    /** 查询参数 */
+    params: unknown;
+    /** 上下文 */
+    context: {
+        pageId: string;
+        pageVersionId: string;
+        componentId?: string;
+        uid?: string;
+        deviceId?: string;
+    };
+    /** 追踪信息 */
+    trace?: TraceInfo;
+    /** 超时（毫秒） */
+    timeoutMs?: number;
+    /** AbortSignal */
+    signal?: AbortSignal;
+}
+/** Data 查询结果 */
+interface DataQueryResult<T = unknown> {
+    /** 是否成功 */
+    ok: boolean;
+    /** 数据 */
+    data?: T;
+    /** 错误信息 */
+    error?: {
+        code: string;
+        message?: string;
+        details?: unknown;
+    };
+}
+/** Data 端口 */
+interface DataPort {
+    query<T = unknown>(input: DataQueryInput): Promise<DataQueryResult<T>>;
+}
+/** Action 执行入参 */
+interface ActionExecuteInput {
+    /** 租户 ID */
+    tenantId?: string;
+    /** 动作类型 */
+    actionType: 'claim' | 'signin' | 'lottery' | 'form_submit' | 'custom' | string;
+    /** 动作参数（用 contracts schema 校验） */
+    payload: unknown;
+    /** 上下文 */
+    context: {
+        pageId: string;
+        pageVersionId: string;
+        componentId?: string;
+        uid?: string;
+        deviceId?: string;
+    };
+    /** 幂等键 */
+    idempotencyKey?: string;
+    /** 追踪信息 */
+    trace?: TraceInfo;
+    /** 超时（毫秒） */
+    timeoutMs?: number;
+    /** AbortSignal */
+    signal?: AbortSignal;
+}
+/** Action 执行结果 */
+interface ActionExecuteResult<T = unknown> {
+    /** 是否成功 */
+    ok: boolean;
+    /** 结果数据（同样用 contracts schema 校验） */
+    data?: T;
+    /** 错误信息 */
+    error?: {
+        code: string;
+        message?: string;
+        details?: unknown;
+    };
+}
+/** Action 端口 */
+interface ActionPort {
+    executeAction<T = unknown>(input: ActionExecuteInput): Promise<ActionExecuteResult<T>>;
+}
+/** 埋点事件 */
+interface TrackEvent {
+    /** 事件名称 */
+    eventName: string;
+    /** 事件类型 */
+    eventType: 'page_view' | 'click' | 'exposure' | 'action' | 'custom';
+    /** 事件属性 */
+    properties?: Record<string, unknown>;
+    /** 时间戳 */
+    timestamp?: number;
+}
+/** Track 入参 */
+interface TrackInput {
+    /** 租户 ID */
+    tenantId?: string;
+    /** 事件列表（批量上报） */
+    events: TrackEvent[];
+    /** 上下文 */
+    context: {
+        pageId: string;
+        pageVersionId: string;
+        uid?: string;
+        deviceId?: string;
+        sessionId?: string;
+    };
+    /** 追踪信息 */
+    trace?: TraceInfo;
+}
+/** Track 端口 */
+interface TrackPort {
+    track(input: TrackInput): Promise<void>;
+}
+/** 聚合 Ports，供 SDK 实现并注入 */
+interface RuntimePorts {
+    /** 租户端口 */
+    tenant?: TenantPort;
+    /** 页面端口 */
+    page: PageRuntimePort;
+    /** 数据端口 */
+    data: DataPort;
+    /** 动作端口 */
+    action: ActionPort;
+    /** 埋点端口 */
+    track: TrackPort;
+}
+
 /**
  * 安全管理器
  * SRI 校验、域名白名单、组件阻止、能力校验等
@@ -2167,4 +2455,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, 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, 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 };
+export { type ASTNode, ActionBridge, type ActionBridgeOptions, ActionError, type ActionExecuteInput, type ActionExecuteResult, type ActionExecutor, type ActionPort, AssetLoader, type AssetLoaderOptions, type AuthInfo, BaseRenderer, type BaseRendererOptions, type CacheStatus, type ClientInfo, ComponentBlockedError, ComponentLoadError, type ComponentLoadResult, type ComponentLoadStatus, ComponentLoader, type ComponentLoaderOptions, type DataPort, type DataQueryInput, type DataQueryResult, 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, PageLoadError, PageLoader, type PageLoaderOptions, type PageRuntimePort as PagePort, type PageResolveResult, type PageRuntimePort, Parser, type PerformanceMetric, type TrackEvent as PortTrackEvent, QueryError, RUNTIME_VERSION, RenderError, type Renderer, type ResolvePageInput, type ResolvePageMeta, type ResolvePageParams, type ResolvePageResult, type ResolveTenantInput, type ResolveTenantResult, type RuntimeContext, type RuntimeError, type RuntimeErrorType, type RuntimeEvent, type RuntimeEventType, type RuntimeOptions, type RuntimePhase, type RuntimePorts, type RuntimeState, SUPPORTED_SCHEMA_VERSION as SCHEMA_VERSION, SUPPORTED_SCHEMA_VERSION, SecurityManager, type SecurityManagerOptions, type Span, type StateListener, StateManager, TelemetryManager, type TelemetryManagerOptions, type TenantPort, type Token, type TokenType, type TraceInfo, type TrackInput, type TrackPayload, type TrackPort, type Unsubscribe, type UserApiAdapter, builtinFunctions, createFallbackElement, createRuntime, registerFallbackComponents };