@lark-apaas/client-toolkit 1.2.28-alpha.67 → 1.2.28-alpha.68

package/lib/auth.d.ts

@@ -1 +1 @@
-export { CanRole, AbilityContext, ROLE_SUBJECT } from '@lark-apaas/auth-sdk';
+export { CanRole, AbilityContext, ROLE_SUBJECT, useAuth, } from '@lark-apaas/auth-sdk';

package/lib/auth.js

@@ -1,2 +1,2 @@
-import { AbilityContext, CanRole, ROLE_SUBJECT } from "@lark-apaas/auth-sdk";
-export { AbilityContext, CanRole, ROLE_SUBJECT };
+import { AbilityContext, CanRole, ROLE_SUBJECT, useAuth } from "@lark-apaas/auth-sdk";
+export { AbilityContext, CanRole, ROLE_SUBJECT, useAuth };

package/lib/components/AppContainer/index.js

@@ -9,6 +9,7 @@ import { PageHoc } from "./PageHoc.js";
 import { reportTeaEvent } from "./utils/tea.js";
 import { useAppInfo } from "../../hooks/index.js";
 import { TrackKey } from "../../types/tea.js";
+import { slardar } from "@lark-apaas/internal-slardar";
 import safety from "./safety.js";
 import { getAppId } from "../../utils/getAppId.js";
 import { isNewPathEnabled } from "../../utils/apiPath.js";
@@ -38,14 +39,33 @@ const App = (props)=>{
         });
     }, []);
     useEffect(()=>{
-        if ('production' === process.env.NODE_ENV) reportTeaEvent({
-            trackKey: TrackKey.VIEW,
-            trackParams: {
-                artifact_uid: getAppId(),
-                agent_id: 'agent_miaoda',
-                url: window.location.href
-            }
-        });
+        if ('production' === process.env.NODE_ENV) {
+            reportTeaEvent({
+                trackKey: TrackKey.VIEW,
+                trackParams: {
+                    artifact_uid: getAppId(),
+                    agent_id: 'agent_miaoda',
+                    url: window.location.href
+                }
+            });
+            const appId = getAppId();
+            const firstRenderTime = Math.round(performance.now());
+            const navEntry = performance.getEntriesByType('navigation')[0];
+            const pageLoadTime = navEntry && navEntry.loadEventEnd > 0 ? Math.round(navEntry.loadEventEnd - navEntry.startTime) : void 0;
+            slardar.sendEvent({
+                name: 'app-first-render',
+                metrics: {
+                    firstRenderTime,
+                    ...null != pageLoadTime ? {
+                        pageLoadTime
+                    } : {}
+                },
+                categories: {
+                    appId: appId ?? 'unknown',
+                    mode: isMiaodaPreview ? 'preview' : 'runtime'
+                }
+            });
+        }
     }, []);
     const appId = getAppId();
     const permissionApiUrl = isNewPathEnabled() ? `/app/${appId}/__runtime__/api/v1/permissions/roles` : `/spark/app/${appId}/runtime/api/v1/permissions/roles`;

package/lib/components/AppContainer/safety.js

@@ -14,17 +14,31 @@ const Component = ()=>{
     const isMobile = useIsMobile();
     const [userinfo, setUserinfo] = useState(null);
     const [isInternetVisible, setIsInternetVisible] = useState(false);
+    const [showBadge, setShowBadge] = useState(true);
+    const [badgeLoaded, setBadgeLoaded] = useState(false);
     const timeoutRef = useRef(null);
     useEffect(()=>{
         const appId = getAppId();
+        const csrfHeaders = {
+            'X-Suda-Csrf-Token': getCsrfToken()
+        };
         const tenantInfoUrl = isNewPathEnabled() ? `/app/${appId}/__runtime__/api/v1/studio/tenant_info` : `/spark/b/${appId}/tenant_info`;
         fetch(tenantInfoUrl, {
-            headers: {
-                'X-Suda-Csrf-Token': getCsrfToken()
-            }
+            headers: csrfHeaders
         }).then((res)=>res.json()).then((data)=>{
             setUserinfo(data?.data?.tenant_info);
             setIsInternetVisible(data?.data?.is_internet_visible);
+        }).catch(()=>{});
+        const getPublishedUrl = isNewPathEnabled() ? `/app/${appId}/__runtime__/api/v1/studio/get_published` : `/spark/b/${appId}/get_published`;
+        fetch(getPublishedUrl, {
+            headers: csrfHeaders
+        }).then((res)=>res.json()).then((data)=>{
+            const badge = data?.data?.app_info?.show_badge;
+            setShowBadge(false !== badge);
+        }).catch(()=>{
+            setShowBadge(true);
+        }).finally(()=>{
+            setBadgeLoaded(true);
         });
     }, []);
     useEffect(()=>{
@@ -39,6 +53,8 @@ const Component = ()=>{
         isMobile
     ]);
     if ('production' !== process.env.NODE_ENV) return null;
+    if (!badgeLoaded) return null;
+    if (!showBadge) return null;
     if (!visible) return null;
     if (isMobile) return /*#__PURE__*/ jsxs(Sheet, {
         open: open,
@@ -47,7 +63,7 @@ const Component = ()=>{
             /*#__PURE__*/ jsx(SheetTrigger, {
                 asChild: true,
                 children: /*#__PURE__*/ jsxs("div", {
-                    className: "fixed right-[12px] bottom-[80px] inline-flex items-center gap-x-1 border-solid border-[#ffffff1a] border px-[10px] py-[6px] bg-[#1f2329e5] backdrop-blur-[5px] shadow-[0px_6px_12px_0px_#41444a0a,0px_8px_24px_8px_#41444a0a] rounded-md text-[#ebebeb)] font-['PingFang_SC'] text-xs leading-[20px] tracking-[0px] z-[10000000]",
+                    className: "fixed right-[12px] bottom-[80px] inline-flex items-center gap-x-1 border-solid border-[#ffffff1a] border px-[10px] py-[6px] bg-[#1f2329e5] backdrop-blur-[5px] shadow-[0px_6px_12px_0px_#41444a0a,0px_8px_24px_8px_#41444a0a] rounded-[6px] text-[#ebebeb)] font-['PingFang_SC'] text-xs leading-[20px] tracking-[0px] z-[10000000]",
                     onClick: ()=>{
                         setOpen(true);
                     },
@@ -242,7 +258,7 @@ const Component = ()=>{
                                     className: "w-full self-stretch shrink-0 flex items-start gap-x-[8px]",
                                     children: [
                                         /*#__PURE__*/ jsx("div", {
-                                            className: "flex-1 flex rounded-lg items-center justify-center h-[34px] border-[0.5px] border-solid border-[#ffffff1c] hover:border-[#ffffff33] bg-[#ffffff08] hover:bg-[#ffffff14] cursor-pointer text-[#ebebeb]",
+                                            className: "flex-1 flex rounded-[8px] items-center justify-center h-[34px] border-[0.5px] border-solid border-[#ffffff1c] hover:border-[#ffffff33] bg-[#ffffff08] hover:bg-[#ffffff14] cursor-pointer text-[#ebebeb]",
                                             "data-custom-element": "safety-close",
                                             onClick: (e)=>{
                                                 e.stopPropagation();
@@ -253,7 +269,7 @@ const Component = ()=>{
                                             children: "不再展示"
                                         }),
                                         /*#__PURE__*/ jsx("div", {
-                                            className: "flex-1 flex rounded-lg items-center justify-center h-[34px] border-[0.5px] border-solid border-[#ffffff1c] hover:border-[#ffffff33] bg-[#ffffff08] hover:bg-[#ffffff14] cursor-pointer text-[#ebebeb]",
+                                            className: "flex-1 flex rounded-[8px] items-center justify-center h-[34px] border-[0.5px] border-solid border-[#ffffff1c] hover:border-[#ffffff33] bg-[#ffffff08] hover:bg-[#ffffff14] cursor-pointer text-[#ebebeb]",
                                             "data-custom-element": "safety-more",
                                             onClick: ()=>{
                                                 window.open('https://miaoda.feishu.cn/landing', '_blank');

package/lib/components/ui/badge.d.ts

@@ -1,7 +1,7 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 declare const badgeVariants: (props?: {
-    variant?: "default" | "destructive" | "secondary" | "outline";
+    variant?: "default" | "destructive" | "outline" | "secondary";
 } & import("class-variance-authority/dist/types").ClassProp) => string;
 declare function Badge({ className, variant, asChild, ...props }: React.ComponentProps<"span"> & VariantProps<typeof badgeVariants> & {
     asChild?: boolean;

package/lib/components/ui/button.d.ts

@@ -1,8 +1,8 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 declare const buttonVariants: (props?: {
-    variant?: "default" | "link" | "destructive" | "secondary" | "outline" | "ghost";
-    size?: "default" | "icon" | "sm" | "lg" | "icon-sm" | "icon-lg";
+    variant?: "default" | "link" | "destructive" | "outline" | "secondary" | "ghost";
+    size?: "default" | "sm" | "lg" | "icon" | "icon-sm" | "icon-lg";
 } & import("class-variance-authority/dist/types").ClassProp) => string;
 declare function Button({ className, variant, size, asChild, ...props }: React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
     asChild?: boolean;

package/lib/components/ui/button.js

@@ -8,7 +8,7 @@ const buttonVariants = cva("inline-flex items-center justify-center gap-2 whites
         variant: {
             default: "bg-primary text-primary-foreground not-disabled:hover:bg-primary/90",
             destructive: "bg-destructive text-white not-disabled:hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
-            outline: "border bg-background not-disabled:hover:bg-accent not-disabled:hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:not-disabled:hover:bg-input/50",
+            outline: "border border-input bg-transparent text-foreground not-disabled:hover:bg-accent not-disabled:hover:text-accent-foreground",
             secondary: "bg-secondary text-secondary-foreground not-disabled:hover:bg-secondary/80",
             ghost: "not-disabled:hover:bg-accent not-disabled:hover:text-accent-foreground dark:not-disabled:hover:bg-accent/50",
             link: "text-primary underline-offset-4 not-disabled:hover:underline"

package/lib/components/ui/confirm.d.ts

@@ -0,0 +1,28 @@
+export interface ConfirmOptions {
+    /** 标题，默认 "提示" */
+    title?: string;
+    /** 内容描述 */
+    message: string;
+    /** 确认按钮文案，默认 "确认" */
+    confirmText?: string;
+    /** 取消按钮文案，默认 "取消" */
+    cancelText?: string;
+    /** 确认按钮样式变体 */
+    variant?: 'default' | 'destructive';
+}
+/**
+ * 函数式确认弹窗，作为 window.confirm 的直接平替。
+ *
+ * @example
+ * // 简单用法（兼容 window.confirm 传参）
+ * const ok = await showConfirm('确定删除吗？');
+ *
+ * // 完整用法
+ * const ok = await showConfirm({
+ *   title: '确认删除',
+ *   message: '删除后不可恢复',
+ *   confirmText: '删除',
+ *   variant: 'destructive',
+ * });
+ */
+export declare function showConfirm(options: string | ConfirmOptions): Promise<boolean>;

package/lib/components/ui/confirm.js

@@ -0,0 +1,83 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import "react";
+import { createRoot } from "react-dom/client";
+import { Content, Description, Overlay, Portal, Root, Title } from "@radix-ui/react-dialog";
+import { Button } from "./button.js";
+import { clsxWithTw } from "../../utils/utils.js";
+function showConfirm(options) {
+    const opts = 'string' == typeof options ? {
+        message: options
+    } : options;
+    const { title = '提示', message, confirmText = '确认', cancelText = '取消', variant = 'default' } = opts;
+    return new Promise((resolve)=>{
+        const container = document.createElement('div');
+        document.body.appendChild(container);
+        const root = createRoot(container);
+        function cleanup() {
+            root.unmount();
+            container.remove();
+        }
+        function handleConfirm() {
+            cleanup();
+            resolve(true);
+        }
+        function handleCancel() {
+            cleanup();
+            resolve(false);
+        }
+        root.render(/*#__PURE__*/ jsx(ConfirmDialog, {
+            title: title,
+            message: message,
+            confirmText: confirmText,
+            cancelText: cancelText,
+            variant: variant,
+            onConfirm: handleConfirm,
+            onCancel: handleCancel
+        }));
+    });
+}
+function ConfirmDialog({ title, message, confirmText, cancelText, variant, onConfirm, onCancel }) {
+    return /*#__PURE__*/ jsx(Root, {
+        defaultOpen: true,
+        onOpenChange: (open)=>{
+            if (!open) onCancel();
+        },
+        children: /*#__PURE__*/ jsxs(Portal, {
+            children: [
+                /*#__PURE__*/ jsx(Overlay, {
+                    className: clsxWithTw('fixed inset-0 z-[99999] bg-black/40', 'data-[state=open]:animate-in data-[state=open]:fade-in-0', 'data-[state=closed]:animate-out data-[state=closed]:fade-out-0')
+                }),
+                /*#__PURE__*/ jsxs(Content, {
+                    className: clsxWithTw('fixed left-1/2 top-1/2 z-[99999] -translate-x-1/2 -translate-y-1/2', 'w-[90vw] max-w-[400px] rounded-lg', 'bg-[var(--popover,var(--color-neutral-00,#fff))] text-[var(--popover-foreground,var(--color-neutral-950,#1f2329))]', 'border border-[var(--border,var(--color-neutral-300,#dee0e3))]', 'shadow-lg p-6', 'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95', 'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95'),
+                    children: [
+                        /*#__PURE__*/ jsx(Title, {
+                            className: clsxWithTw('text-base font-medium leading-6', 'text-[var(--foreground,var(--color-neutral-950,#1f2329))]'),
+                            children: title
+                        }),
+                        /*#__PURE__*/ jsx(Description, {
+                            className: clsxWithTw('mt-2 text-sm leading-5', 'text-[var(--muted-foreground,var(--color-neutral-700,#646a73))]'),
+                            children: message
+                        }),
+                        /*#__PURE__*/ jsxs("div", {
+                            className: clsxWithTw('mt-6 flex justify-end gap-2'),
+                            children: [
+                                /*#__PURE__*/ jsx(Button, {
+                                    variant: "outline",
+                                    className: "!bg-transparent !text-inherit",
+                                    onClick: onCancel,
+                                    children: cancelText
+                                }),
+                                /*#__PURE__*/ jsx(Button, {
+                                    variant: variant,
+                                    onClick: onConfirm,
+                                    children: confirmText
+                                })
+                            ]
+                        })
+                    ]
+                })
+            ]
+        })
+    });
+}
+export { showConfirm };

package/lib/hooks/useCurrentUserProfile.d.ts

@@ -1,5 +1,11 @@
 import { IUserProfile } from '../apis/udt-types';
-export interface ICompatibilityUserProfile extends IUserProfile {
+/**
+ * useCurrentUserProfile 的返回类型。
+ * 初始状态为空对象 `{}`（所有字段均为 undefined），异步获取用户信息后字段才会被填充。
+ * 使用时必须通过可选链或空值合并进行安全访问，如 `userInfo?.user_id`。
+ * 判断是否已加载完成应使用 `if (!userInfo?.user_id)` 而非 `if (!userInfo)`（因为空对象是 truthy）。
+ */
+export type ICompatibilityUserProfile = Partial<IUserProfile & {
     /**
      * @deprecated please use `name`
      */
@@ -8,5 +14,14 @@ export interface ICompatibilityUserProfile extends IUserProfile {
      * @deprecated please use `avatar`
      */
     userAvatar: string;
-}
-export declare const useCurrentUserProfile: () => ICompatibilityUserProfile;
+}>;
+export declare const useCurrentUserProfile: () => Partial<IUserProfile & {
+    /**
+     * @deprecated please use `name`
+     */
+    userName: string;
+    /**
+     * @deprecated please use `avatar`
+     */
+    userAvatar: string;
+}>;

package/lib/index.d.ts

@@ -1,4 +1,6 @@
 export declare const capabilityClient: import("@lark-apaas/client-capability").CapabilityClient;
+export { showConfirm } from './components/ui/confirm';
+export type { ConfirmOptions } from './components/ui/confirm';
 declare const _default: {
     version: string;
 };

package/lib/index.js

@@ -5,6 +5,7 @@ import { isNewPathEnabled } from "./utils/apiPath.js";
 import { logger } from "./logger/index.js";
 import { showToast } from "./components/ui/toast.js";
 import { version } from "../package.json";
+import { showConfirm } from "./components/ui/confirm.js";
 const _appId = getAppId();
 const _acquireUploadUrl = isNewPathEnabled() ? `/app/${_appId}/__runtime__/api/v1/studio/plugins/tmp_files/acquire_upload_url` : "/af/api/v1/studio/plugins/tmp_files/acquire_upload_url";
 const _acquireDownloadUrl = isNewPathEnabled() ? `/app/${_appId}/__runtime__/api/v1/studio/plugins/tmp_files/acquire_download_url` : "/af/api/v1/studio/plugins/tmp_files/acquire_download_url";
@@ -25,4 +26,4 @@ const capabilityClient = createClient({
 const src = {
     version: version
 };
-export { capabilityClient, src as default };
+export { capabilityClient, src as default, showConfirm };

package/lib/integrations/getCurrentUserProfile.d.ts

@@ -1,5 +1,11 @@
 import { IUserProfile } from '../apis/udt-types';
-export declare function getCurrentUserProfile(): IUserProfile;
+/**
+ * 获取当前用户信息。
+ * 返回 Partial<IUserProfile>，因为初始值来自 window._userInfo，
+ * 该值在运行时始终为空对象 {}，所有字段均为 undefined。
+ * 异步获取用户信息后才会被填充为完整的 IUserProfile。
+ */
+export declare function getCurrentUserProfile(): Partial<IUserProfile>;
 /**
  * @deprecated 请使用 getCurrentUserProfile 代替
  */

package/lib/integrations/services/ChatService.d.ts

@@ -0,0 +1,12 @@
+import type { BatchGetChatsResponse, SearchChatsParams, SearchChatsResponse } from './types';
+export type ChatServiceConfig = {
+    getAppId?: () => string | null | undefined;
+    searchChatsUrl?: (appId: string) => string;
+    listChatsUrl?: (appId: string) => string;
+};
+export declare class ChatService {
+    private config;
+    constructor(config?: ChatServiceConfig);
+    searchChats(params: SearchChatsParams): Promise<SearchChatsResponse>;
+    listChatsByIds(chatIds: string[]): Promise<BatchGetChatsResponse>;
+}

package/lib/integrations/services/ChatService.js

@@ -0,0 +1,67 @@
+import { getAppId } from "../../utils/getAppId.js";
+const DEFAULT_CONFIG = {
+    getAppId: ()=>getAppId(),
+    searchChatsUrl: (appId)=>`/app/${appId}/__runtime__/api/v1/account/search`,
+    listChatsUrl: (appId)=>`/app/${appId}/__runtime__/api/v1/account/chat/list_chats`
+};
+class ChatService {
+    config;
+    constructor(config = {}){
+        this.config = {
+            ...DEFAULT_CONFIG,
+            ...config
+        };
+    }
+    async searchChats(params) {
+        const appId = this.config.getAppId();
+        if (!appId) throw new Error('Failed to get appId');
+        const response = await fetch(this.config.searchChatsUrl(appId), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                query: params.query,
+                filters: {
+                    userParam: {
+                        commonParam: {
+                            searchable: false
+                        }
+                    },
+                    departmentParam: {
+                        commonParam: {
+                            searchable: false
+                        }
+                    },
+                    chatParam: {
+                        commonParam: {
+                            searchable: true,
+                            pageSize: params.pageSize ?? 100,
+                            offset: params.offset ?? 0
+                        }
+                    }
+                }
+            }),
+            credentials: 'include'
+        });
+        if (!response.ok) throw new Error('Failed to search chats');
+        return response.json();
+    }
+    async listChatsByIds(chatIds) {
+        const appId = this.config.getAppId();
+        if (!appId) throw new Error('Failed to get appId');
+        const response = await fetch(this.config.listChatsUrl(appId), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                chatIDList: chatIds
+            }),
+            credentials: 'include'
+        });
+        if (!response.ok) throw new Error('Failed to fetch chats by ids');
+        return response.json();
+    }
+}
+export { ChatService };

package/lib/integrations/services/UserService.d.ts

@@ -1,12 +1,14 @@
-import type { BatchGetUsersResponse, SearchUsersParams, SearchUsersResponse } from './types';
+import type { BatchGetUsersResponse, ConvertExternalContactResponse, SearchUsersParams, SearchUsersResponse } from './types';
 export type UserServiceConfig = {
     getAppId?: () => string | null | undefined;
     searchUserUrl?: (appId: string) => string;
     listUsersUrl?: (appId: string) => string;
+    convertExternalContactUrl?: (appId: string) => string;
 };
 export declare class UserService {
     private config;
     constructor(config?: UserServiceConfig);
     searchUsers(params: SearchUsersParams): Promise<SearchUsersResponse>;
     listUsersByIds(userIds: string[]): Promise<BatchGetUsersResponse>;
+    convertExternalContact(larkUserID: string): Promise<ConvertExternalContactResponse>;
 }

package/lib/integrations/services/UserService.js

@@ -3,7 +3,8 @@ import { isNewPathEnabled } from "../../utils/apiPath.js";
 const DEFAULT_CONFIG = {
     getAppId: ()=>getAppId(),
     searchUserUrl: (appId)=>isNewPathEnabled() ? `/app/${appId}/__runtime__/api/v1/account/search_user` : `/af/app/${appId}/runtime/api/v1/account/search_user`,
-    listUsersUrl: (appId)=>isNewPathEnabled() ? `/app/${appId}/__runtime__/api/v1/account/list_users` : `/af/app/${appId}/runtime/api/v1/account/list_users`
+    listUsersUrl: (appId)=>isNewPathEnabled() ? `/app/${appId}/__runtime__/api/v1/account/list_users` : `/af/app/${appId}/runtime/api/v1/account/list_users`,
+    convertExternalContactUrl: (appId)=>isNewPathEnabled() ? `/app/${appId}/__runtime__/api/v1/account/convert_lark_user` : `/af/app/${appId}/runtime/api/v1/account/convert_lark_user`
 };
 class UserService {
     config;
@@ -43,5 +44,23 @@ class UserService {
         if (!response.ok) throw new Error('Failed to fetch users by ids');
         return response.json();
     }
+    async convertExternalContact(larkUserID) {
+        const appId = this.config.getAppId();
+        if (!appId) throw new Error('Failed to get appId');
+        const response = await fetch(this.config.convertExternalContactUrl(appId), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                larkUserID
+            }),
+            credentials: 'include'
+        });
+        if (!response.ok) throw new Error('Failed to convert external contact');
+        const data = await response.json();
+        if (!data?.data?.userInfo?.userID) throw new Error('Invalid response from convert external contact');
+        return data;
+    }
 }
 export { UserService };

package/lib/integrations/services/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types';
 export * from './UserService';
 export * from './DepartmentService';
+export * from './ChatService';
 export * from './UserProfileService';

package/lib/integrations/services/index.js

@@ -1,4 +1,5 @@
 export * from "./types.js";
 export * from "./UserService.js";
 export * from "./DepartmentService.js";
+export * from "./ChatService.js";
 export * from "./UserProfileService.js";

package/lib/integrations/services/types.d.ts

@@ -15,6 +15,7 @@ export type UserInfo = {
     userType: '_employee' | '_externalUser' | '_anonymousUser';
     department: DepartmentBasic;
     email?: string;
+    tenantName?: string;
 };
 export type DepartmentInfo = {
     departmentID: string;
@@ -33,6 +34,7 @@ export type SearchUsersParams = {
     query?: string;
     offset?: number;
     pageSize?: number;
+    searchExternalContact?: boolean;
 };
 export type SearchUsersResponse = {
     data: {
@@ -41,6 +43,14 @@ export type SearchUsersResponse = {
     };
     status_code: string;
 };
+export type ConvertExternalContactResponse = {
+    data: {
+        userInfo: {
+            tenantID: number;
+            userID: number;
+        };
+    };
+};
 export type BatchGetUsersResponse = {
     data: {
         userInfoMap: Record<string, UserInfo & SearchAvatar>;
@@ -62,6 +72,40 @@ export type SearchDepartmentsResponse = {
     };
     status_code: string;
 };
+export type ChatInfo = {
+    /** 群组 ID */
+    chatID: string;
+    /** 群组名称（国际化文本） */
+    name: I18nText;
+    /** 头像：URL 或 16 进制 RGB 颜色 */
+    avatar: string;
+    /** 是否是外部群 */
+    isExternal?: boolean;
+    /** 群成员数量（不包括机器人），搜索接口返回，批量查询接口不返回 */
+    userCount?: number;
+};
+export type SearchChatsParams = {
+    query?: string;
+    offset?: number;
+    pageSize?: number;
+};
+export type SearchChatsResponse = {
+    data: {
+        result: {
+            chatResult?: {
+                total: number;
+                items: ChatInfo[];
+            };
+        };
+    };
+    status_code: string;
+};
+export type BatchGetChatsResponse = {
+    data: {
+        chatInfoMap: Record<string, ChatInfo>;
+    };
+    status_code: string;
+};
 export type UserProfileAccountStatus = 0 | 1 | 2 | 3 | 4;
 export type SimpleUserProfileInfo = {
     name?: string;

package/lib/utils/axiosConfig.js

@@ -4,6 +4,92 @@ import { logger } from "../apis/logger.js";
 import { getStacktrace } from "../logger/selected-logs.js";
 import { safeStringify } from "./safeStringify.js";
 import { slardar } from "@lark-apaas/internal-slardar";
+import { normalizeBasePath } from "./utils.js";
+const APP_CLIENT_API_LOG_TYPE = 'app_client_api_log';
+function stripBasePath(urlPath) {
+    const base = normalizeBasePath(process.env.CLIENT_BASE_PATH);
+    if (base && urlPath.startsWith(base)) return urlPath.slice(base.length) || '/';
+    return urlPath;
+}
+let _pageRoutes = null;
+function getPageRouteDefinitions() {
+    if (_pageRoutes) return _pageRoutes;
+    try {
+        const raw = process.env.__PAGE_ROUTE_DEFINITIONS__;
+        if (raw) {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed)) {
+                _pageRoutes = parsed;
+                return _pageRoutes;
+            }
+        }
+    } catch  {}
+    _pageRoutes = [];
+    return _pageRoutes;
+}
+let _apiRoutes = null;
+function getApiRouteDefinitions() {
+    if (_apiRoutes) return _apiRoutes;
+    try {
+        const raw = process.env.__API_ROUTE_DEFINITIONS__;
+        if (raw) {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed)) {
+                _apiRoutes = parsed;
+                return _apiRoutes;
+            }
+        }
+    } catch  {}
+    _apiRoutes = [];
+    return _apiRoutes;
+}
+function matchRoute(concretePath, routes) {
+    const segments = concretePath.split('/').filter(Boolean);
+    for (const route of routes){
+        const routeSegments = route.path.split('/').filter(Boolean);
+        if (routeSegments.length !== segments.length) continue;
+        let match = true;
+        for(let i = 0; i < routeSegments.length; i++)if (!routeSegments[i].startsWith(':')) {
+            if (routeSegments[i] !== segments[i]) {
+                match = false;
+                break;
+            }
+        }
+        if (match) return route.path;
+    }
+    return null;
+}
+function matchApiRoute(method, concretePath) {
+    const routes = getApiRouteDefinitions();
+    const segments = concretePath.split('/').filter(Boolean);
+    for (const route of routes){
+        if ('*' !== route.method && route.method !== method) continue;
+        const routeSegments = route.path.split('/').filter(Boolean);
+        if (routeSegments.length !== segments.length) continue;
+        let match = true;
+        for(let i = 0; i < routeSegments.length; i++)if (!routeSegments[i].startsWith(':')) {
+            if (routeSegments[i] !== segments[i]) {
+                match = false;
+                break;
+            }
+        }
+        if (match) return route.path;
+    }
+    return null;
+}
+function getRefererPath() {
+    try {
+        if ('undefined' == typeof window || !window.location?.pathname) return '/';
+        const rawPath = stripBasePath(window.location.pathname);
+        return matchRoute(rawPath, getPageRouteDefinitions()) || rawPath;
+    } catch  {
+        return '/';
+    }
+}
+function getApiField(method, path) {
+    const matched = matchApiRoute(method, path);
+    return `${method} ${matched || path}`;
+}
 const isValidResponse = (resp)=>null != resp && 'object' == typeof resp && 'config' in resp && null !== resp.config && void 0 !== resp.config && 'object' == typeof resp.config && 'status' in resp && 'number' == typeof resp.status && 'data' in resp;
 async function logResponse(ok, responseOrError) {
     if (isValidResponse(responseOrError)) {
@@ -139,13 +225,20 @@ function handleSpanEnd(cfg, response, error) {
         const errorMessage = error?.message || '未知错误';
         const url = response?.request?.responseURL || errorResponse?.request?.responseURL || cfg.url || "";
         const method = (cfg.method || 'GET').toUpperCase();
-        const path = url.split('?')[0].replace(/^https?:\/\/[^/]+/, '') || '/';
+        const rawPath = url.split('?')[0].replace(/^https?:\/\/[^/]+/, '') || '/';
+        const path = stripBasePath(rawPath);
+        const durationMs = startTime ? Date.now() - startTime : void 0;
+        const referer_path = getRefererPath();
+        const api = getApiField(method, path);
+        const type = APP_CLIENT_API_LOG_TYPE;
         const logData = {
             method,
             path,
             url,
-            duration_ms: startTime ? Date.now() - startTime : void 0,
-            status: response ? response.status : errorResponse.status || 0
+            duration_ms: durationMs,
+            status: response ? response.status : errorResponse.status || 0,
+            referer_path,
+            type
         };
         if (error) logData.error_message = errorMessage;
         if ('undefined' != typeof navigator) logData.user_agent = navigator.userAgent;
@@ -158,7 +251,19 @@ function handleSpanEnd(cfg, response, error) {
         const responseData = response?.data || errorResponse?.data;
         if (responseData) logData.response = responseData;
         const level = error ? 'ERROR' : 'INFO';
-        observable.log(level, safeStringify(logData), {}, currentSpan);
+        observable.log(level, safeStringify(logData), {
+            referer_path,
+            api,
+            type,
+            duration_ms: durationMs
+        }, currentSpan);
+        if ('function' == typeof currentSpan.setAttributes) currentSpan.setAttributes({
+            referer_path,
+            api,
+            duration_ms: durationMs,
+            module: 'app_web',
+            source_type: 'platform'
+        });
         'function' == typeof currentSpan.end && currentSpan.end();
     } catch (e) {
         console.error('[AxiosTrace] Log span failed:', e);
@@ -240,6 +345,11 @@ function initAxiosConfig(axiosInstance) {
         const csrfToken = window.csrfToken;
         if (csrfToken) config.headers['X-Suda-Csrf-Token'] = csrfToken;
         if ('undefined' != typeof window && window.location?.pathname) config.headers['X-Page-Route'] = window.location.pathname;
+        const refererPath = getRefererPath();
+        config.headers['Rpc-Persist-Apaas-Observability-Referer-Path'] = refererPath;
+        const reqMethod = (config.method || 'GET').toUpperCase();
+        const requestPath = stripBasePath((config.url || '').split('?')[0]);
+        config.headers['Rpc-Persist-Apaas-Observability-Api'] = getApiField(reqMethod, requestPath);
         return config;
     }, (error)=>Promise.reject(error));
     instance.interceptors.response.use((response)=>response, (error)=>{
@@ -262,7 +372,18 @@ function initAxiosConfig(axiosInstance) {
                     name: 'toolkit_axios_403_downgrade',
                     categories: {
                         url: String(error.config?.url || ''),
-                        method: String(error.config?.method || '')
+                        method: String(error.config?.method || ''),
+                        ...'production' !== process.env.NODE_ENV && {
+                            responseData: (()=>{
+                                try {
+                                    const data = error.response?.data;
+                                    if (!data) return '';
+                                    return 'string' == typeof data ? data.slice(0, 512) : JSON.stringify(data).slice(0, 512);
+                                } catch  {
+                                    return '';
+                                }
+                            })()
+                        }
                     }
                 });
                 return error.response;
@@ -273,7 +394,19 @@ function initAxiosConfig(axiosInstance) {
             categories: {
                 url: String(error.config?.url || ''),
                 method: String(error.config?.method || ''),
-                status: String(error.response?.status || '')
+                status: String(error.response?.status || ''),
+                ...'production' !== process.env.NODE_ENV && {
+                    errorMessage: String(error.message || ''),
+                    responseData: (()=>{
+                        try {
+                            const data = error.response?.data;
+                            if (!data) return '';
+                            return 'string' == typeof data ? data.slice(0, 512) : JSON.stringify(data).slice(0, 512);
+                        } catch  {
+                            return '';
+                        }
+                    })()
+                }
             }
         });
         return Promise.reject(error);

package/lib/utils/hmr-api.d.ts

@@ -9,6 +9,12 @@
  * @see docs/RFC_HMR_API.md
  */
 export interface HmrApi {
+    /**
+     * 注册 HMR 更新前回调（模块替换之前触发）
+     * @param callback 回调函数
+     * @returns cleanup 函数，用于取消注册
+     */
+    onBeforeApply?(callback: () => void): () => void;
     /**
      * 注册 HMR 成功回调
      * @param callback 成功回调函数
@@ -24,7 +30,7 @@ export interface HmrApi {
 }
 declare global {
     interface Window {
-        __VITE_HMR__?: HmrApi;
+        __VITE_HMR__?: Required<HmrApi>;
     }
 }
 /**

package/lib/utils/safeStringify.js

@@ -12,6 +12,11 @@ function safeStringify(obj) {
             if (value instanceof Set) return Array.from(value);
             if (void 0 === value) return 'undefined';
             if ('symbol' == typeof value) return value.toString();
+            if (value instanceof Error) return {
+                name: value.name,
+                message: value.message,
+                stack: value.stack
+            };
             return value;
         });
     } catch  {

package/lib/utils/safeStringify.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/utils/safeStringify.spec.js

@@ -0,0 +1,125 @@
+import { describe, expect, it } from "vitest";
+import { mapLogLevel, processLogParams, safeStringify } from "./safeStringify.js";
+describe('safeStringify', ()=>{
+    it('should serialize a plain string', ()=>{
+        expect(safeStringify('hello')).toBe('"hello"');
+    });
+    it('should serialize a plain object', ()=>{
+        expect(safeStringify({
+            a: 1
+        })).toBe('{"a":1}');
+    });
+    it('should handle circular references', ()=>{
+        const obj = {
+            a: 1
+        };
+        obj.self = obj;
+        expect(safeStringify(obj)).toBe('{"a":1,"self":"[Circular]"}');
+    });
+    it('should serialize BigInt as string', ()=>{
+        expect(safeStringify(BigInt(123))).toBe('"123"');
+    });
+    it('should serialize Date as ISO string', ()=>{
+        const date = new Date('2024-01-01T00:00:00.000Z');
+        expect(safeStringify(date)).toBe('"2024-01-01T00:00:00.000Z"');
+    });
+    it('should serialize Map as object', ()=>{
+        const map = new Map([
+            [
+                'key',
+                'value'
+            ]
+        ]);
+        expect(safeStringify(map)).toBe('{"key":"value"}');
+    });
+    it('should serialize Set as array', ()=>{
+        const set = new Set([
+            1,
+            2,
+            3
+        ]);
+        expect(safeStringify(set)).toBe('[1,2,3]');
+    });
+    it('should serialize undefined as string', ()=>{
+        expect(safeStringify({
+            a: void 0
+        })).toBe('{"a":"undefined"}');
+    });
+    it('should serialize Symbol as string', ()=>{
+        expect(safeStringify({
+            s: Symbol('test')
+        })).toBe('{"s":"Symbol(test)"}');
+    });
+    it('should serialize Error with name, message and stack', ()=>{
+        const err = new Error('something went wrong');
+        const result = JSON.parse(safeStringify(err));
+        expect(result.name).toBe('Error');
+        expect(result.message).toBe('something went wrong');
+        expect(result.stack).toContain('something went wrong');
+    });
+    it('should serialize Error subclass with correct name', ()=>{
+        const err = new TypeError('bad type');
+        const result = JSON.parse(safeStringify(err));
+        expect(result.name).toBe('TypeError');
+        expect(result.message).toBe('bad type');
+    });
+    it('should serialize Error nested in object', ()=>{
+        const err = new Error('inner error');
+        const result = JSON.parse(safeStringify({
+            err
+        }));
+        expect(result.err.name).toBe('Error');
+        expect(result.err.message).toBe('inner error');
+    });
+    it('should return empty string on unexpected failure', ()=>{
+        const bad = {
+            toJSON () {
+                throw new Error('fail');
+            }
+        };
+        expect(safeStringify(bad)).toBe('');
+    });
+});
+describe('processLogParams', ()=>{
+    it('should serialize single argument directly', ()=>{
+        expect(processLogParams([
+            'hello'
+        ])).toBe('"hello"');
+    });
+    it('should serialize single object argument', ()=>{
+        expect(processLogParams([
+            {
+                a: 1
+            }
+        ])).toBe('{"a":1}');
+    });
+    it('should serialize multiple arguments as indexed object', ()=>{
+        const result = JSON.parse(processLogParams([
+            'msg',
+            {
+                key: 'val'
+            }
+        ]));
+        expect(result['0']).toBe('msg');
+        expect(result['1']).toEqual({
+            key: 'val'
+        });
+    });
+});
+describe('mapLogLevel', ()=>{
+    it('should map error to ERROR', ()=>{
+        expect(mapLogLevel('error')).toBe('ERROR');
+    });
+    it('should map info to INFO', ()=>{
+        expect(mapLogLevel('info')).toBe('INFO');
+    });
+    it('should map success to INFO', ()=>{
+        expect(mapLogLevel('success')).toBe('INFO');
+    });
+    it('should map warn to WARN', ()=>{
+        expect(mapLogLevel('warn')).toBe('WARN');
+    });
+    it('should default unknown level to INFO', ()=>{
+        expect(mapLogLevel('debug')).toBe('INFO');
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/client-toolkit",
-  "version": "1.2.28-alpha.67",
+  "version": "1.2.28-alpha.68",
   "types": "./lib/index.d.ts",
   "main": "./lib/index.js",
   "files": [
@@ -98,13 +98,13 @@
   "dependencies": {
     "@ant-design/colors": "^7.2.1",
     "@ant-design/cssinjs": "^1.24.0",
-    "@data-loom/js": "0.4.9",
-    "@lark-apaas/aily-web-sdk": "0.0.2-alpha.18",
-    "@lark-apaas/auth-sdk": "^0.1.2",
+    "@data-loom/js": "0.4.13",
+    "@lark-apaas/aily-web-sdk": "^0.0.8",
+    "@lark-apaas/auth-sdk": "^0.1.3",
     "@lark-apaas/client-capability": "^0.1.6",
     "@lark-apaas/internal-slardar": "^0.0.3",
-    "@lark-apaas/miaoda-inspector": "^1.0.20",
-    "@lark-apaas/observable-web": "^1.0.4",
+    "@lark-apaas/miaoda-inspector": "^1.0.23",
+    "@lark-apaas/observable-web": "1.0.2-alpha.11",
     "@radix-ui/react-avatar": "^1.1.10",
     "@radix-ui/react-popover": "^1.1.15",
     "@radix-ui/react-slot": "^1.2.3",