@lark-apaas/client-toolkit-lite 1.1.7-alpha.9 → 1.1.7

package/dist/index.d.cts

@@ -6,6 +6,7 @@ import { ClassValue } from 'clsx';
 import { AxiosInstance } from 'axios';
 import * as _lark_apaas_dataloom from '@lark-apaas/dataloom';
 import * as _lark_apaas_client_capability from '@lark-apaas/client-capability';
+import { observable } from '@lark-apaas/observable-web';
 
 /**
  * Inject minimal __REACT_DEVTOOLS_GLOBAL_HOOK__ before React loads.
@@ -61,7 +62,7 @@ interface LogWithMeta {
     meta?: LogMeta;
 }
 
-declare const logger: {
+declare let logger: {
     debug(message: unknown, ...args: unknown[]): void;
     info(message: unknown, ...args: unknown[]): void;
     warn(message: unknown, ...args: unknown[]): void;
@@ -78,8 +79,9 @@ declare const logger: {
  * 执行顺序：
  * 1. React DevTools Hook（必须在 React 加载之前）
  * 2. Axios 配置（仅 CSRF token 注入）
- * 3. Logger 模块 side-effect（dev 下注册 interceptErrors）
- * 4. Iframe Bridge（仅 dev + iframe 嵌入）
+ * 3. 可观测初始化（OpenTelemetry traces/logs/metrics）
+ * 4. Logger 模块 side-effect（dev 下注册 interceptErrors）
+ * 5. Iframe Bridge（仅 dev + iframe 嵌入）
  *
  * 不包含 server-log SSE：jsPage 是纯前端，没有"业务后端日志"概念。
  */
@@ -116,12 +118,15 @@ declare const PagePlaceholder: React__default.FC<{
  *
  * 链路：业务代码 throw → react-error-boundary 捕获 → 渲染本组件
  *   → submitPostMessage({ type: 'RenderError' }) 通知妙搭外壳
- *   → 外壳左下角弹「告诉妙搭修复」
+ *   → logger.log meta.repairMessage 让外壳 sandbox-console 弹「一键修复」
  *
- * HMR success 时自动 resetErrorBoundary，让用户改完代码页面自动恢复。
- *
- * 跟全栈 toolkit 的 ErrorRender 一致，砍掉了 t() i18n，文案 hardcode 中文
- * （jsPage 用户基本都是中文环境）。
+ * HMR 恢复策略按构建工具区分：
+ *   - **vite**: ErrorBoundary 状态下 React Refresh family map 找不到 fiber，
+ *     resetErrorBoundary 让 children 重新 mount 时 import 仍是旧引用 → 死循环。
+ *     vite 模式（检测到 window.__VITE_HMR__）必须 `window.location.reload()`
+ *     才能让模块图完整重载（这是 vite 官方对 ErrorBoundary 场景的 recommended fallback）。
+ *   - **webpack/rspack**: 模块 cache 可被 HMR 直接替换，resetErrorBoundary 让 children
+ *     重新 mount 时 import 拿到新版本 → 正常恢复，不需要 reload。
  */
 declare const ErrorRender: React__default.FC<{
     error: unknown;
@@ -329,6 +334,23 @@ declare function getDataloom(): Promise<ReturnType<typeof createDataLoomClient>>
 
 declare const capabilityClient: _lark_apaas_client_capability.CapabilityClient;
 
+/**
+ * 核心 Trace 方法：用于执行并追踪异步函数。
+ * 使用代理模式而非直接 bind，确保在调用时获取最新的 observable 实例状态。
+ */
+declare const trace: (...args: Parameters<typeof observable.trace>) => Promise<unknown>;
+
+/**
+ * 初始化 OpenTelemetry 可观测（traces / logs / metrics）。
+ * 从老 client-toolkit 搬过来——逻辑保持一致：
+ *   - serviceName 固定 "app"
+ *   - dev / prod 区分 AppEnv
+ *   - collector URL 区分新旧 path 形态（/app/:appId vs /spark/app/:appId）
+ *
+ * 内部 try/catch 吞错——SDK 启动失败不应阻断应用渲染。
+ */
+declare const initObservable: () => void;
+
 interface TrackParams {
     trackKey: TrackKey;
     trackParams?: Record<string, unknown>;
@@ -496,4 +518,4 @@ declare namespace cover {
   export { cover_abstractArt3dRenderingCoverImg1 as abstractArt3dRenderingCoverImg1, cover_abstractArt3dRenderingCoverImg2 as abstractArt3dRenderingCoverImg2, cover_abstractArt3dRenderingCoverImg3 as abstractArt3dRenderingCoverImg3, cover_abstractArt3dRenderingCoverImg4 as abstractArt3dRenderingCoverImg4, cover_abstractArt3dRenderingCoverImg5 as abstractArt3dRenderingCoverImg5, cover_abstractArt3dRenderingCoverImg6 as abstractArt3dRenderingCoverImg6, cover_appealClothingCoverImg1 as appealClothingCoverImg1, cover_appealClothingCoverImg2 as appealClothingCoverImg2, cover_appealClothingCoverImg3 as appealClothingCoverImg3, cover_appealClothingCoverImg4 as appealClothingCoverImg4, cover_appealClothingCoverImg5 as appealClothingCoverImg5, cover_appealClothingCoverImg6 as appealClothingCoverImg6, cover_architectureCoverImg1 as architectureCoverImg1, cover_architectureCoverImg2 as architectureCoverImg2, cover_architectureCoverImg3 as architectureCoverImg3, cover_architectureCoverImg4 as architectureCoverImg4, cover_architectureCoverImg5 as architectureCoverImg5, cover_architectureCoverImg6 as architectureCoverImg6, cover_officeCoverImg1 as officeCoverImg1, cover_officeCoverImg2 as officeCoverImg2, cover_officeCoverImg3 as officeCoverImg3, cover_officeCoverImg4 as officeCoverImg4, cover_officeCoverImg5 as officeCoverImg5, cover_officeCoverImg6 as officeCoverImg6, cover_sceneryCoverImg1 as sceneryCoverImg1, cover_sceneryCoverImg2 as sceneryCoverImg2, cover_sceneryCoverImg3 as sceneryCoverImg3, cover_sceneryCoverImg4 as sceneryCoverImg4, cover_sceneryCoverImg5 as sceneryCoverImg5, cover_sceneryCoverImg6 as sceneryCoverImg6, cover_technologyInternetCoverImg1 as technologyInternetCoverImg1, cover_technologyInternetCoverImg2 as technologyInternetCoverImg2, cover_technologyInternetCoverImg3 as technologyInternetCoverImg3, cover_technologyInternetCoverImg4 as technologyInternetCoverImg4, cover_technologyInternetCoverImg5 as technologyInternetCoverImg5, cover_technologyInternetCoverImg6 as technologyInternetCoverImg6 };
 }
 
-export { ActiveLink, AppContainer, type AppInfoPayload, ErrorRender, type IFileAttachment, type IJson, type IUserProfile, type LogLevel, type LogWithMeta, NavLink, PagePlaceholder, QueryProvider, TrackKey, type TrackParams, UniversalLink, Welcome, avatar as avatarImages, axiosForBackend, banner as bannerImages, capabilityClient, clsxWithTw, copyToClipboard, cover as coverImages, getAppId, getAppInfo, getAxiosForBackend, getCsrfToken, getCurrentUserProfile, getDataloom, getEnvPath, getWsPath, initAxiosConfig, isIOS, isIpad, isMobile, isPreview, logger, normalizeBasePath, reportTeaEvent, resolveAppUrl, safeStringify, scopedStorage, useAppInfo, useCurrentUserProfile, useIsMobile, useLogout };
+export { ActiveLink, AppContainer, type AppInfoPayload, ErrorRender, type IFileAttachment, type IJson, type IUserProfile, type LogLevel, type LogWithMeta, NavLink, PagePlaceholder, QueryProvider, TrackKey, type TrackParams, UniversalLink, Welcome, avatar as avatarImages, axiosForBackend, banner as bannerImages, capabilityClient, clsxWithTw, copyToClipboard, cover as coverImages, getAppId, getAppInfo, getAxiosForBackend, getCsrfToken, getCurrentUserProfile, getDataloom, getEnvPath, getWsPath, initAxiosConfig, initObservable, isIOS, isIpad, isMobile, isPreview, logger, normalizeBasePath, reportTeaEvent, resolveAppUrl, safeStringify, scopedStorage, trace, useAppInfo, useCurrentUserProfile, useIsMobile, useLogout };

package/dist/index.d.ts

@@ -6,6 +6,7 @@ import { ClassValue } from 'clsx';
 import { AxiosInstance } from 'axios';
 import * as _lark_apaas_dataloom from '@lark-apaas/dataloom';
 import * as _lark_apaas_client_capability from '@lark-apaas/client-capability';
+import { observable } from '@lark-apaas/observable-web';
 
 /**
  * Inject minimal __REACT_DEVTOOLS_GLOBAL_HOOK__ before React loads.
@@ -61,7 +62,7 @@ interface LogWithMeta {
     meta?: LogMeta;
 }
 
-declare const logger: {
+declare let logger: {
     debug(message: unknown, ...args: unknown[]): void;
     info(message: unknown, ...args: unknown[]): void;
     warn(message: unknown, ...args: unknown[]): void;
@@ -78,8 +79,9 @@ declare const logger: {
  * 执行顺序：
  * 1. React DevTools Hook（必须在 React 加载之前）
  * 2. Axios 配置（仅 CSRF token 注入）
- * 3. Logger 模块 side-effect（dev 下注册 interceptErrors）
- * 4. Iframe Bridge（仅 dev + iframe 嵌入）
+ * 3. 可观测初始化（OpenTelemetry traces/logs/metrics）
+ * 4. Logger 模块 side-effect（dev 下注册 interceptErrors）
+ * 5. Iframe Bridge（仅 dev + iframe 嵌入）
  *
  * 不包含 server-log SSE：jsPage 是纯前端，没有"业务后端日志"概念。
  */
@@ -116,12 +118,15 @@ declare const PagePlaceholder: React__default.FC<{
  *
  * 链路：业务代码 throw → react-error-boundary 捕获 → 渲染本组件
  *   → submitPostMessage({ type: 'RenderError' }) 通知妙搭外壳
- *   → 外壳左下角弹「告诉妙搭修复」
+ *   → logger.log meta.repairMessage 让外壳 sandbox-console 弹「一键修复」
  *
- * HMR success 时自动 resetErrorBoundary，让用户改完代码页面自动恢复。
- *
- * 跟全栈 toolkit 的 ErrorRender 一致，砍掉了 t() i18n，文案 hardcode 中文
- * （jsPage 用户基本都是中文环境）。
+ * HMR 恢复策略按构建工具区分：
+ *   - **vite**: ErrorBoundary 状态下 React Refresh family map 找不到 fiber，
+ *     resetErrorBoundary 让 children 重新 mount 时 import 仍是旧引用 → 死循环。
+ *     vite 模式（检测到 window.__VITE_HMR__）必须 `window.location.reload()`
+ *     才能让模块图完整重载（这是 vite 官方对 ErrorBoundary 场景的 recommended fallback）。
+ *   - **webpack/rspack**: 模块 cache 可被 HMR 直接替换，resetErrorBoundary 让 children
+ *     重新 mount 时 import 拿到新版本 → 正常恢复，不需要 reload。
  */
 declare const ErrorRender: React__default.FC<{
     error: unknown;
@@ -329,6 +334,23 @@ declare function getDataloom(): Promise<ReturnType<typeof createDataLoomClient>>
 
 declare const capabilityClient: _lark_apaas_client_capability.CapabilityClient;
 
+/**
+ * 核心 Trace 方法：用于执行并追踪异步函数。
+ * 使用代理模式而非直接 bind，确保在调用时获取最新的 observable 实例状态。
+ */
+declare const trace: (...args: Parameters<typeof observable.trace>) => Promise<unknown>;
+
+/**
+ * 初始化 OpenTelemetry 可观测（traces / logs / metrics）。
+ * 从老 client-toolkit 搬过来——逻辑保持一致：
+ *   - serviceName 固定 "app"
+ *   - dev / prod 区分 AppEnv
+ *   - collector URL 区分新旧 path 形态（/app/:appId vs /spark/app/:appId）
+ *
+ * 内部 try/catch 吞错——SDK 启动失败不应阻断应用渲染。
+ */
+declare const initObservable: () => void;
+
 interface TrackParams {
     trackKey: TrackKey;
     trackParams?: Record<string, unknown>;
@@ -496,4 +518,4 @@ declare namespace cover {
   export { cover_abstractArt3dRenderingCoverImg1 as abstractArt3dRenderingCoverImg1, cover_abstractArt3dRenderingCoverImg2 as abstractArt3dRenderingCoverImg2, cover_abstractArt3dRenderingCoverImg3 as abstractArt3dRenderingCoverImg3, cover_abstractArt3dRenderingCoverImg4 as abstractArt3dRenderingCoverImg4, cover_abstractArt3dRenderingCoverImg5 as abstractArt3dRenderingCoverImg5, cover_abstractArt3dRenderingCoverImg6 as abstractArt3dRenderingCoverImg6, cover_appealClothingCoverImg1 as appealClothingCoverImg1, cover_appealClothingCoverImg2 as appealClothingCoverImg2, cover_appealClothingCoverImg3 as appealClothingCoverImg3, cover_appealClothingCoverImg4 as appealClothingCoverImg4, cover_appealClothingCoverImg5 as appealClothingCoverImg5, cover_appealClothingCoverImg6 as appealClothingCoverImg6, cover_architectureCoverImg1 as architectureCoverImg1, cover_architectureCoverImg2 as architectureCoverImg2, cover_architectureCoverImg3 as architectureCoverImg3, cover_architectureCoverImg4 as architectureCoverImg4, cover_architectureCoverImg5 as architectureCoverImg5, cover_architectureCoverImg6 as architectureCoverImg6, cover_officeCoverImg1 as officeCoverImg1, cover_officeCoverImg2 as officeCoverImg2, cover_officeCoverImg3 as officeCoverImg3, cover_officeCoverImg4 as officeCoverImg4, cover_officeCoverImg5 as officeCoverImg5, cover_officeCoverImg6 as officeCoverImg6, cover_sceneryCoverImg1 as sceneryCoverImg1, cover_sceneryCoverImg2 as sceneryCoverImg2, cover_sceneryCoverImg3 as sceneryCoverImg3, cover_sceneryCoverImg4 as sceneryCoverImg4, cover_sceneryCoverImg5 as sceneryCoverImg5, cover_sceneryCoverImg6 as sceneryCoverImg6, cover_technologyInternetCoverImg1 as technologyInternetCoverImg1, cover_technologyInternetCoverImg2 as technologyInternetCoverImg2, cover_technologyInternetCoverImg3 as technologyInternetCoverImg3, cover_technologyInternetCoverImg4 as technologyInternetCoverImg4, cover_technologyInternetCoverImg5 as technologyInternetCoverImg5, cover_technologyInternetCoverImg6 as technologyInternetCoverImg6 };
 }
 
-export { ActiveLink, AppContainer, type AppInfoPayload, ErrorRender, type IFileAttachment, type IJson, type IUserProfile, type LogLevel, type LogWithMeta, NavLink, PagePlaceholder, QueryProvider, TrackKey, type TrackParams, UniversalLink, Welcome, avatar as avatarImages, axiosForBackend, banner as bannerImages, capabilityClient, clsxWithTw, copyToClipboard, cover as coverImages, getAppId, getAppInfo, getAxiosForBackend, getCsrfToken, getCurrentUserProfile, getDataloom, getEnvPath, getWsPath, initAxiosConfig, isIOS, isIpad, isMobile, isPreview, logger, normalizeBasePath, reportTeaEvent, resolveAppUrl, safeStringify, scopedStorage, useAppInfo, useCurrentUserProfile, useIsMobile, useLogout };
+export { ActiveLink, AppContainer, type AppInfoPayload, ErrorRender, type IFileAttachment, type IJson, type IUserProfile, type LogLevel, type LogWithMeta, NavLink, PagePlaceholder, QueryProvider, TrackKey, type TrackParams, UniversalLink, Welcome, avatar as avatarImages, axiosForBackend, banner as bannerImages, capabilityClient, clsxWithTw, copyToClipboard, cover as coverImages, getAppId, getAppInfo, getAxiosForBackend, getCsrfToken, getCurrentUserProfile, getDataloom, getEnvPath, getWsPath, initAxiosConfig, initObservable, isIOS, isIpad, isMobile, isPreview, logger, normalizeBasePath, reportTeaEvent, resolveAppUrl, safeStringify, scopedStorage, trace, useAppInfo, useCurrentUserProfile, useIsMobile, useLogout };