@doubao-dev/framework 0.0.42 → 0.1.1

package/dist/index.d.ts

@@ -103,7 +103,66 @@ import { VoidFunctionComponent } from 'react';
 
 export declare type AgentEventCallback = (payload: AgentEventPayload) => void;
 
-declare type AgentEventPayload = Record<string, unknown>;
+export declare type AgentEventHandler = (name: string, payload: AgentEventPayload) => void;
+
+export declare type AgentEventPayload = Record<string, unknown>;
+
+declare interface AgreePrivacyResult {
+    /**
+     * 用户是否同意隐私协议授权。
+     */
+    result: boolean;
+}
+
+declare interface AIAppMetadata {
+    /**
+     *
+     *  豆包应用 ID
+     *
+     */
+    appId: string;
+    /**
+     * 应用名称
+     */
+    name?: string;
+    /**
+     * 应用描述
+     */
+    description?: string;
+    /**
+     * 应用图标
+     *
+     * 1x, 2x, 3x 分别对应 1x, 2x, 3x 倍的图标
+     */
+    icons?: Icons;
+    /**
+     * 应用关键词
+     */
+    keywords?: string[];
+    /**
+     * 应用版本
+     */
+    version?: string;
+    /**
+     * 是否声明小程序已适配深色模式
+     */
+    darkMode?: boolean;
+    /**
+     * 应用级对话框能力配置
+     */
+    chat?: AppletChatConfig;
+}
+
+export declare type AIToolContext = MessageMeta & {
+    /**
+     * callback Id
+     */
+    callbackId: string;
+    /**
+     * feature map
+     */
+    featureMap: Record<string, string> | undefined;
+};
 
 export declare type AIViewContext = MessageMeta & {
     /**
@@ -141,6 +200,44 @@ export declare type AIViewContext = MessageMeta & {
     };
 };
 
+export declare type AnyObject = Record<string, any>;
+
+export declare type App<T extends DefineAppOptions = DefineAppOptions> = T & {
+    readonly eventChannel: EventChannel;
+    __APP__: boolean;
+    __UI__: boolean;
+};
+
+declare type AppAIMeta = Omit<AIAppMetadata, 'appId'> & {
+    appId?: string;
+    package?: string;
+};
+
+declare interface AppletChatConfig {
+    /**
+     * App-level chat feature overrides.
+     */
+    features?: AppletChatFeaturesConfig;
+}
+
+declare interface AppletChatFeatureConfig {
+    /**
+     * Whether the chat feature is enabled.
+     */
+    enabled: boolean;
+}
+
+declare interface AppletChatFeaturesConfig {
+    /**
+     * Camera entry configuration.
+     */
+    camera?: AppletChatFeatureConfig;
+    /**
+     * Extra actions entry configuration.
+     */
+    extraActions?: AppletChatFeatureConfig;
+}
+
 export { Attributes }
 
 export { CElement }
@@ -201,12 +298,216 @@ export { createElement }
 
 export { createRef }
 
+/** 当前页面栈中的页面信息。 */
 export declare interface CurrentPage {
+    /** 页面路由。 */
     route: string;
+    /**
+     * @since 0.1.0
+     * 页面查询参数。
+     */
+    query: Record<string, string>;
 }
 
 export { CustomComponentPropsWithRef }
 
+export declare function defineApp<T extends DefineAppOptions>(options: T & ThisType<T & {
+    readonly aiMeta: AppAIMeta;
+    readonly eventChannel: EventChannel;
+}>): App<T>;
+
+export declare interface DefineAppOptions {
+    [key: string]: any;
+    /**
+     * @deprecated Configure app metadata in src/app.config.ts instead.
+     *
+     * @example
+     * ```ts
+     * // src/app.config.ts
+     * import { defineAppConfig } from '@doubao-dev/framework/config';
+     *
+     * export default defineAppConfig({
+     *   appId: 'your-app-id',
+     *   name: 'Demo App',
+     *   description: 'Describe what this app can do',
+     *   icons: 'https://example.com/icon.png',
+     *   keywords: ['demo', 'doubao']
+     * });
+     * ```
+     */
+    aiMeta?: AppAIMeta;
+    /**
+     * App launched
+     */
+    onLaunch?: () => void;
+    /**
+     * On page opened
+     */
+    onPageOpened?: (params: {
+        viewId: string;
+    }) => void;
+    /**
+     * Handle an event sent by the Agent to the app.
+     */
+    onAgentEvent?: AgentEventHandler;
+    /**
+     * On foreground
+     */
+    onForeground?: () => void;
+    /**
+     * On background
+     */
+    onBackground?: () => void;
+    /**
+     * On destroy
+     */
+    onDestroy?: () => void;
+    /**
+     * Handle errors from other App callbacks or tools in the same Applet.
+     */
+    onError?: (e: Error) => void;
+}
+
+export declare interface DefineFunctionalToolOptions extends Tool {
+    onApply: (input: string, context: AIToolContext) => string | object | Promise<string | object>;
+}
+
+export declare function defineLoginApi(api: LoginApi): LoginApi;
+
+/**
+ * 定义 MCP 登录页面
+ * @param options 定义 MCP 登录页面的选项
+ * @returns 智能服务 MCP 登录页面
+ */
+export declare function defineLoginPage<Data extends AnyObject>(options: Omit<DefinePageToolOptions<Data>, 'aiMeta'> & ThisType<Readonly<PageInstanceMethods<Data>>>): Page<Data>;
+
+export declare function definePage<Data extends AnyObject>(options: DefinePageToolOptions<Data> & ThisType<Readonly<PageInstanceMethods<Data>>>): Page<Data>;
+
+export declare interface DefinePageToolOptions<Data extends AnyObject> extends DefineUIToolOptions<Data, PageToolExtraMetadata> {
+    /**
+     * @deprecated Configure page metadata in src/app.config.ts instead.
+     *
+     * Use `pages` entries in `src/app.config.ts`. For example,
+     * `pages/home/index` maps to `src/pages/home/index.tsx`, and
+     * `pages/account/demo/index` maps to `src/pages/account/demo/index.tsx`.
+     *
+     * @example
+     * ```ts
+     * // src/app.config.ts
+     * import { defineAppConfig } from '@doubao-dev/framework/config';
+     *
+     * export default defineAppConfig({
+     *   appId: 'your-app-id',
+     *   pages: ['pages/home/index']
+     * });
+     * ```
+     */
+    aiMeta?: PageToolMetadata;
+}
+
+export declare function definePrivacyApi(api: PrivacyApi): PrivacyApi;
+
+/**
+ * 定义 MCP 同意登录和隐私协议卡片组件
+ * @param options 定义 MCP 同意登录和隐私协议卡片组件的选项
+ * @returns MCP 同意登录和隐私协议卡片组件
+ */
+export declare function definePrivacyLoginWidget<Data extends AnyObject>(options: Omit<DefineWidgetToolOptions<Data>, 'aiMeta'> & ThisType<Readonly<WidgetInstanceMethods<Data>>>): Widget<Data>;
+
+/**
+ * @deprecated Export a default Client Tool handler and configure it in `app.config.ts` instead.
+ */
+export declare function defineTool(options: DefineFunctionalToolOptions & ThisType<Readonly<FunctionalToolInstanceMethods>>): FunctionalTool;
+
+export declare interface DefineUIToolOptions<Data extends AnyObject, Extra extends AnyObject = AnyObject> extends Tool<Extra> {
+    /**
+     * Initial data
+     */
+    data?: Data;
+    /**
+     * Trigger on view created
+     * @returns
+     */
+    onCreated?: () => void;
+    /**
+     * It is triggered after the view is rendered and will only be called once in the view's life cycle.
+     * @returns
+     */
+    onMounted?: () => void;
+    /**
+     * 1. It is triggered when the view is first displayed.
+     * 2. It is triggered when the view is displayed again after being hidden.
+     * @returns
+     */
+    onShow?: () => void;
+    /**
+     * It is triggered when the view is hidden.
+     * @returns
+     */
+    onHide?: () => void;
+    /**
+     * It is triggered when the view is destroyed.
+     * @returns
+     */
+    onDestroy?: () => void;
+    /**
+     * It is triggered when an error occurs.
+     * @param e
+     * @returns
+     */
+    onError?: (e: Error) => void;
+    /**
+     * Render function
+     * Use getViewData() and getViewContext() to access data and context
+     * @returns
+     */
+    render: () => ReactNode;
+}
+
+export declare function defineWidget<Data extends AnyObject>(options: DefineWidgetToolOptions<Data> & ThisType<Readonly<WidgetInstanceMethods<Data>>>): Widget<Data>;
+
+export declare interface DefineWidgetToolOptions<Data extends AnyObject> extends DefineUIToolOptions<Data, WidgetToolExtraMetadata> {
+    /**
+     * @deprecated Configure widget metadata in src/app.config.ts instead.
+     *
+     * Use `widgets` entries in `src/app.config.ts`. For example,
+     * `widgets/card/index` maps to `src/widgets/card/index.tsx`, and
+     * `widgets/api/demo/index` maps to `src/widgets/api/demo/index.tsx`.
+     *
+     * @example
+     * ```ts
+     * // src/app.config.ts
+     * import { defineAppConfig } from '@doubao-dev/framework/config';
+     *
+     * export default defineAppConfig({
+     *   appId: 'your-app-id',
+     *   widgets: [
+     *     {
+     *       entry: 'widgets/card/index',
+     *       id: 'card-widget',
+     *       name: 'Card Widget',
+     *       description: 'Show card content',
+     *       border: true
+     *     }
+     *   ]
+     * });
+     * ```
+     */
+    aiMeta?: WidgetToolMetadata;
+    /**
+     * 1. It is triggered when the app returns to the foreground from the background.
+     * 2. It is triggered when phone is unlocked.
+     * @returns
+     */
+    onForeground?: () => void;
+    /**
+     * 1. It is triggered when the app is moved to the background.
+     * 2. It is triggered when phone is locked.
+     * @returns
+     */
+    onBackground?: () => void;
+}
+
 export { DependencyList }
 
 export { DeprecatedLifecycle }
@@ -225,6 +526,19 @@ export { ElementRef }
 
 export { ElementType }
 
+export declare type EventCallback = (...args: any[]) => void;
+
+export declare class EventChannel {
+    private readonly handleError;
+    private listeners;
+    constructor(handleError?: (error: unknown) => void);
+    emit(eventName: string, ...args: any[]): void;
+    on(eventName: string, callback: EventCallback): void;
+    once(eventName: string, callback: EventCallback): void;
+    off(eventName: string, callback?: EventCallback): void;
+    private addListener;
+}
+
 export { ExoticComponent }
 
 export { Factory }
@@ -241,24 +555,49 @@ export { ForwardRefRenderFunction }
 
 export { Fragment }
 
+export declare interface FunctionalTool extends DefineFunctionalToolOptions {
+    __FUNCTIONAL__: boolean;
+}
+
+declare type FunctionalToolInstanceMethods = Tool<ToolMetadata>;
+
 export { FunctionComponent }
 
 export { FunctionComponentElement }
 
 export { FunctionComponentFactory }
 
-export declare function getCurrentPages(): CurrentPage[];
+declare function getApp_2<T extends App = App>(): T;
+export { getApp_2 as getApp }
+
+export declare function getCurrentPages(): {
+    route: string;
+    query: Record<string, string>;
+}[];
 
 export { GetDerivedStateFromError }
 
 export { GetDerivedStateFromProps }
 
+declare interface GetPhoneNumberResult {
+    /**
+     * 获取手机号结果码。
+     */
+    code?: string;
+    /**
+     * 获取手机号结果信息。
+     */
+    message?: string;
+}
+
 export declare function getViewContext(): any;
 
 export declare function getViewData<T extends Record<string, any>>(): T;
 
 export declare function getWidgetInstanceId(): string | undefined;
 
+declare type Icons = string | Record<'1x' | '2x' | '3x', string>;
+
 export { isValidElement }
 
 export { JSXElementConstructor }
@@ -275,6 +614,13 @@ declare type LifecycleCallback = () => void;
 
 declare type LifecycleErrorCallback = (error: Error) => void;
 
+export declare interface LoginApi {
+    onLogin: (res: LoginResult) => Promise<void> | void;
+    onRefuseLogin: () => Promise<void> | void;
+}
+
+export declare type LoginResult = GetPhoneNumberResult;
+
 export { memo }
 
 export { MemoExoticComponent }
@@ -322,6 +668,36 @@ export { NamedExoticComponent }
 
 export { NewLifecycle }
 
+/**
+ * Register the runtime error handler.
+ *
+ * Calling this again replaces the previously registered handler.
+ */
+export declare function onError(callback: (error: Error) => void): void;
+
+export declare interface Page<Data extends AnyObject = AnyObject> extends DefineUIToolOptions<Data> {
+    __UI__: boolean;
+    __PAGE__: boolean;
+}
+
+declare type PageInstanceMethods<Data extends AnyObject> = UIInstanceMethods<Data, PageToolExtraMetadata>;
+
+declare type PageToolExtraMetadata = {
+    /**
+     * The page navbar title
+     */
+    title?: string;
+};
+
+export declare type PageToolMetadata = ToolMeta & PageToolExtraMetadata;
+
+export declare type PrivacyAgreeResult = AgreePrivacyResult;
+
+export declare interface PrivacyApi {
+    onAgreePrivacy: (res: PrivacyAgreeResult) => Promise<void> | void;
+    onRefusePrivacy: () => Promise<void> | void;
+}
+
 export { PropsWithChildren }
 
 export { PropsWithoutRef }
@@ -382,10 +758,57 @@ export { Suspense }
 
 export { SVGFactory }
 
+export declare interface Tool<Extra extends AnyObject = AnyObject> {
+    aiMeta?: ToolMeta & Extra;
+}
+
+export declare interface ToolMeta {
+    /**
+     * unique identifier
+     */
+    id: string;
+    /**
+     * name of the tool
+     */
+    name?: string;
+    /**
+     * description of the tool
+     */
+    description?: string;
+    /**
+     * Widget title type
+     * - none: 默认，无标题
+     * - normal: 常规标题
+     * - float: 浮动标题
+     */
+    titleType?: 'none' | 'normal' | 'float';
+}
+
+export declare type ToolMetadata = {
+    /**
+     * specifies when a call to a tool will time out, in ms.
+     */
+    timeout?: number;
+};
+
 export { TransitionFunction }
 
 export { TransitionStartFunction }
 
+export declare interface UIInstanceMethods<Data extends AnyObject, Extra extends AnyObject = AnyObject> extends Tool<Extra> {
+    /**
+     * Instance data
+     */
+    data: Data;
+    /**
+     * Set data asynchronously and trigger view re-rendering
+     * @param data
+     * @param callback
+     * @returns
+     */
+    setData: (data: Partial<Data> & AnyObject, callback?: () => void) => Promise<void>;
+}
+
 export declare function useAgentEvent(eventName: string, callback: AgentEventCallback): void;
 
 export declare function useBackground(callback: LifecycleCallback): void;
@@ -453,4 +876,37 @@ export { VFC }
 
 export { VoidFunctionComponent }
 
+export declare interface Widget<Data extends AnyObject = AnyObject> extends DefineWidgetToolOptions<Data> {
+    __UI__: boolean;
+    __WIDGET__: boolean;
+    setData: (data: Partial<Data>, callback?: () => void) => void;
+}
+
+declare type WidgetInstanceMethods<Data extends AnyObject> = UIInstanceMethods<Data, WidgetToolExtraMetadata>;
+
+declare type WidgetToolExtraMetadata = {
+    /**
+     * Widget box type in Chat UI
+     */
+    boxType?: 'inbox' | 'full_box';
+    /**
+     * Whether add widget border
+     */
+    border?: boolean;
+    /**
+     * Keywords of things
+     */
+    keywords?: string[];
+    /**
+     * Icons
+     */
+    icons?: Icons;
+    /**
+     * Set extra widget properties
+     */
+    prop?: string;
+};
+
+export declare type WidgetToolMetadata = ToolMeta & WidgetToolExtraMetadata;
+
 export { }

package/jsx-runtime.d.ts

@@ -14,6 +14,7 @@ export namespace JSX {
   interface IntrinsicClassAttributes<T> extends React.JSX.IntrinsicClassAttributes<T> {}
   interface IntrinsicElements {
     // Extended components
+    audio: import('./components.d.ts').AudioProps;
     button: import('./components.d.ts').ButtonProps;
     canvas: import('./components.d.ts').CanvasProps;
     map: import('./components.d.ts').MapProps;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doubao-dev/framework",
-  "version": "0.0.42",
+  "version": "0.1.1",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -78,6 +78,7 @@
   "scripts": {
     "sync:declarations": "node scripts/sync-declarations.cjs",
     "dev": "tsc -p tsconfig.json -w",
-    "build": "npm run sync:declarations && rimraf dist && rslib build && tsc"
+    "build": "npm run sync:declarations && rimraf dist && rslib build && tsc && npm run sanitize:api-docs",
+    "sanitize:api-docs": "node scripts/sanitize-api-declarations.cjs"
   }
 }

package/types.d.ts

@@ -1,5 +1,8 @@
 // Generated file. Do not edit this file directly.
 // CSS modules
+/** App version tag resolved by the build and used for deployment. */
+declare const __VERSION_TAG__: string | undefined;
+
 type CSSModuleClasses = { readonly [key: string]: string };
 
 declare module '*.module.css' {