@syllm/brickly-sdk 0.1.0

package/dist/api.d.ts

@@ -0,0 +1,412 @@
+import { EventEmitter } from 'node:events';
+import { BppTransport, type BppTransportOptions } from './runtime';
+import { type BrickUiWindowOptions, type BrickWindowNetworkEvent, type BrickWindowMethod, type CommandInvocationContext, type PlatformClipboardReadResult, type PlatformClipboardContent, type PlatformClipboardSetResult, type PlatformInputKeyboardTapPayload, type PlatformInputMousePointPayload, type PlatformScreenCaptureOptions, type PlatformScreenCaptureResult, type PlatformScreenColorPickOptions, type PlatformScreenColorPickResult, type PlatformScreenDesktopCaptureOptions, type PlatformScreenDesktopCaptureSource, type PlatformScreenDisplay, type PlatformScreenPoint, type PlatformScreenRect, type PlatformSystemPathName, type PlatformScreenshotRegionOptions, type PlatformScreenshotResult } from './protocol';
+/**
+ * 跨 Brick 命令类型映射，由 typegen 生成的声明文件扩展。
+ *
+ * 形态：
+ * interface CommandMap {
+ *   'com.example.foo': {
+ *     run: { input: { text: string }; output: string }
+ *   }
+ * }
+ */
+export interface CommandMap {
+}
+type KnownBrickId = keyof CommandMap & string;
+type KnownCommandId<TBrickId extends KnownBrickId> = keyof CommandMap[TBrickId] & string;
+type CommandShape<TBrickId extends KnownBrickId, TCommandId extends KnownCommandId<TBrickId>> = CommandMap[TBrickId][TCommandId] extends {
+    input: infer TInput;
+    output: infer TOutput;
+} ? {
+    input: TInput;
+    output: TOutput;
+} : {
+    input: unknown;
+    output: unknown;
+};
+type CommandInput<TBrickId extends KnownBrickId, TCommandId extends KnownCommandId<TBrickId>> = CommandShape<TBrickId, TCommandId>['input'];
+type CommandOutput<TBrickId extends KnownBrickId, TCommandId extends KnownCommandId<TBrickId>> = CommandShape<TBrickId, TCommandId>['output'];
+type InvokeReturn<TBrickId extends string, TCommandId extends string, TFallback> = TBrickId extends KnownBrickId ? TCommandId extends KnownCommandId<TBrickId> ? CommandOutput<TBrickId, TCommandId> : TFallback : TFallback;
+type InvokeInput<TBrickId extends string, TCommandId extends string> = TBrickId extends KnownBrickId ? TCommandId extends KnownCommandId<TBrickId> ? CommandInput<TBrickId, TCommandId> : unknown : unknown;
+/** 在 onCommand handler 中可用的上下文对象。 */
+export interface CommandContext {
+    /** 当前请求 id（用于 progress / chunk / output 与 cancel 关联）。 */
+    readonly requestId: string;
+    /** 当前 commandId。 */
+    readonly commandId: string;
+    /** 本次 command 的可信调用来源。 */
+    readonly invocation: CommandInvocationContext;
+    /** 注册取消回调；宿主下发 command.cancel 时触发。 */
+    onCancel(handler: () => void): void;
+    /** 用户协作式取消判断：handler 自行轮询。 */
+    isCancelled(): boolean;
+    /** 进度（0~1）。 */
+    progress(value: number, message?: string): void;
+    /** 追加流片段到指定具名输出（省略 name 表示匿名输出）。 */
+    chunk(chunk: unknown, name?: string): void;
+    /** 一次性覆盖某个具名输出。 */
+    output(name: string, value: unknown): void;
+    /** 跨 Brick 调用命令。未指定 profileId 时使用目标 Brick 默认 Profile。 */
+    invoke<T = unknown, TBrickId extends string = string, TCommandId extends string = string>(brickId: TBrickId, commandId: TCommandId, input?: InvokeInput<TBrickId, TCommandId>, options?: InvokeOptions): Promise<InvokeReturn<TBrickId, TCommandId, T>>;
+    /** 跨 Brick 流式调用命令，实时返回目标命令的 progress/chunk/output/result。 */
+    invokeStream<TBrickId extends string = string, TCommandId extends string = string>(brickId: TBrickId, commandId: TCommandId, input?: InvokeInput<TBrickId, TCommandId>, options?: InvokeOptions): AsyncIterable<HostInvokeStreamEvent>;
+    /** 打开跨 Brick 会话。会话关闭前，宿主保持目标 Brick 实例不被回收。 */
+    openSession<TBrickId extends string = string>(brickId: TBrickId, options?: SessionOptions): Promise<BrickSession<TBrickId>>;
+    /** 子窗口与事件 API（与 brick.ui / brick.events 同源，便于在 handler 内调用）。 */
+    readonly ui: UiApi;
+    readonly events: EventsApi;
+    readonly platform: PlatformApi;
+    /** 由 host.hello.config 注入的当前 Profile 配置快照。 */
+    readonly config: Record<string, unknown>;
+}
+export type CommandHandler = (ctx: CommandContext, input: unknown) => unknown | Promise<unknown>;
+export interface InvokeOptions {
+    /** 目标 Brick Profile ID；不传则由宿主选择目标 Brick 默认 Profile。 */
+    profileId?: string;
+}
+export type HostInvokeStreamEvent = {
+    type: 'progress';
+    progress: number;
+    message?: string;
+} | {
+    type: 'chunk';
+    name?: string;
+    chunk: unknown;
+} | {
+    type: 'output';
+    name: string;
+    value: unknown;
+} | {
+    type: 'result';
+    result?: unknown;
+} | {
+    type: 'error';
+    error: unknown;
+};
+export interface SessionOptions {
+    /** 目标 Brick Profile ID；不传则由宿主选择目标 Brick 默认 Profile。 */
+    profileId?: string;
+}
+export declare class BrickSession<TBrickId extends string = string> {
+    private readonly transport;
+    readonly id: string;
+    readonly brickId: TBrickId;
+    readonly profileId?: string | undefined;
+    constructor(transport: BppTransport, id: string, brickId: TBrickId, profileId?: string | undefined);
+    invoke<T = unknown, TCommandId extends string = string>(commandId: TCommandId, input?: InvokeInput<TBrickId, TCommandId>): Promise<InvokeReturn<TBrickId, TCommandId, T>>;
+    close(): Promise<void>;
+}
+/** BrickWindowMethod 中可发送的方法签名。 */
+export interface UiApi {
+    /**
+     * 创建一个 Brick 子窗口。url 可为 https:// / file:// / 相对 Brick rootDir 的路径。
+     * 返回 WindowHandle，可继续调用窗口方法或订阅事件。
+     */
+    createBrowserWindow(url: string, options?: BrickUiWindowOptions): Promise<WindowHandle>;
+    /** 列出本 Brick 持有的子窗口（来自宿主权威视图）。 */
+    listWindows(): Promise<unknown[]>;
+}
+/** event.notify 事件订阅 API。 */
+export interface EventsApi {
+    /**
+     * 订阅事件总线上的事件。返回取消函数。
+     * 仅本地路由：宿主侧的实际订阅声明在 manifest.subscriptions 中。
+     */
+    on(event: string, handler: (payload: unknown, envelope: EventEnvelope) => void): () => void;
+    /** 主动发布事件到总线。 */
+    publish(event: string, payload?: unknown): Promise<void>;
+}
+export interface PlatformApi {
+    screenshot: {
+        selectRegion(options?: PlatformScreenshotRegionOptions): Promise<PlatformScreenshotResult>;
+    };
+    screen: {
+        captureRegion(options?: PlatformScreenCaptureOptions): Promise<PlatformScreenCaptureResult>;
+        pickColor(options?: PlatformScreenColorPickOptions): Promise<PlatformScreenColorPickResult>;
+        getPrimaryDisplay(): Promise<PlatformScreenDisplay>;
+        getAllDisplays(): Promise<PlatformScreenDisplay[]>;
+        getCursorScreenPoint(): Promise<PlatformScreenPoint>;
+        getDisplayNearestPoint(point: PlatformScreenPoint): Promise<PlatformScreenDisplay>;
+        getDisplayMatching(rect: PlatformScreenRect): Promise<PlatformScreenDisplay>;
+        screenToDipPoint(point: PlatformScreenPoint): Promise<PlatformScreenPoint>;
+        dipToScreenPoint(point: PlatformScreenPoint): Promise<PlatformScreenPoint>;
+        screenToDipRect(rect: PlatformScreenRect): Promise<PlatformScreenRect>;
+        dipToScreenRect(rect: PlatformScreenRect): Promise<PlatformScreenRect>;
+        desktopCaptureSources(options: PlatformScreenDesktopCaptureOptions): Promise<PlatformScreenDesktopCaptureSource[]>;
+    };
+    input: {
+        keyboardTap(key: string, ...modifiers: string[]): Promise<void>;
+        keyboardTap(payload: PlatformInputKeyboardTapPayload): Promise<void>;
+        mouseMove(x: number, y: number): Promise<void>;
+        mouseMove(payload: PlatformInputMousePointPayload): Promise<void>;
+        mouseClick(x: number, y: number): Promise<void>;
+        mouseClick(payload: PlatformInputMousePointPayload): Promise<void>;
+        mouseDoubleClick(x: number, y: number): Promise<void>;
+        mouseDoubleClick(payload: PlatformInputMousePointPayload): Promise<void>;
+        mouseRightClick(x: number, y: number): Promise<void>;
+        mouseRightClick(payload: PlatformInputMousePointPayload): Promise<void>;
+    };
+    clipboard: {
+        readContent(): Promise<PlatformClipboardReadResult>;
+        setContent(content: PlatformClipboardContent): Promise<PlatformClipboardSetResult>;
+    };
+    system: {
+        showNotification(body: string, clickFeatureCode?: string): Promise<void>;
+        shellOpenPath(fullPath: string): Promise<void>;
+        shellTrashItem(fullPath: string): Promise<void>;
+        shellShowItemInFolder(fullPath: string): Promise<void>;
+        shellOpenExternal(url: string): Promise<void>;
+        shellBeep(): Promise<void>;
+        getNativeId(): Promise<string>;
+        getAppName(): Promise<string>;
+        getAppVersion(): Promise<string>;
+        getPath(name: PlatformSystemPathName): Promise<string>;
+        getFileIcon(filePath: string): Promise<string>;
+        readCurrentFolderPath(): Promise<string>;
+        readCurrentBrowserUrl(): Promise<string>;
+        isDev(): Promise<boolean>;
+        isMacOS(): Promise<boolean>;
+        isWindows(): Promise<boolean>;
+        isLinux(): Promise<boolean>;
+    };
+}
+export interface EventEnvelope {
+    event: string;
+    payload: unknown;
+    sourceBrickId: string;
+    publishedAt: number;
+}
+/** 子窗口句柄。close() 调 host.ui.closeWindow，其余方法走 host.ui.callWindow。 */
+export declare class WindowHandle extends EventEmitter {
+    readonly id: number;
+    private readonly transport;
+    private closed;
+    constructor(transport: BppTransport, windowId: number);
+    /** 通用：调用窗口白名单方法。 */
+    call<T = unknown>(method: BrickWindowMethod, args?: unknown[]): Promise<T>;
+    private sendToWebContents;
+    /** 订阅该窗口的网络检查事件。需在 createBrowserWindow options.network 中开启。 */
+    onNetwork(handler: (event: BrickWindowNetworkEvent) => void): this;
+    setBounds(bounds: {
+        x?: number;
+        y?: number;
+        width?: number;
+        height?: number;
+    }): Promise<void>;
+    getBounds(): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    setPosition(x: number, y: number): Promise<void>;
+    getPosition(): Promise<[number, number]>;
+    setSize(width: number, height: number): Promise<void>;
+    getSize(): Promise<[number, number]>;
+    setOpacity(opacity: number): Promise<void>;
+    getOpacity(): Promise<number>;
+    setBackgroundColor(color: string): Promise<void>;
+    setHasShadow(hasShadow: boolean): Promise<void>;
+    setTitle(title: string): Promise<void>;
+    getTitle(): Promise<string>;
+    setAlwaysOnTop(flag: boolean, level?: string): Promise<void>;
+    isAlwaysOnTop(): Promise<boolean>;
+    setIgnoreMouseEvents(ignore: boolean, opts?: {
+        forward?: boolean;
+    }): Promise<void>;
+    setSkipTaskbar(skip: boolean): Promise<void>;
+    setVisibleOnAllWorkspaces(visible: boolean, opts?: {
+        visibleOnFullScreen?: boolean;
+    }): Promise<void>;
+    setResizable(resizable: boolean): Promise<void>;
+    setMovable(movable: boolean): Promise<void>;
+    setFocusable(focusable: boolean): Promise<void>;
+    minimize(): Promise<void>;
+    maximize(): Promise<void>;
+    unmaximize(): Promise<void>;
+    restore(): Promise<void>;
+    hide(): Promise<void>;
+    show(): Promise<void>;
+    showInactive(): Promise<void>;
+    focus(): Promise<void>;
+    blur(): Promise<void>;
+    isDestroyed(): Promise<boolean>;
+    isVisible(): Promise<boolean>;
+    isFocused(): Promise<boolean>;
+    isMinimized(): Promise<boolean>;
+    isMaximized(): Promise<boolean>;
+    loadURL(url: string, options?: Record<string, unknown>): Promise<void>;
+    loadFile(filePath: string, options?: Record<string, unknown>): Promise<void>;
+    reload(): Promise<void>;
+    setContentBounds(bounds: {
+        x?: number;
+        y?: number;
+        width?: number;
+        height?: number;
+    }): Promise<void>;
+    getContentBounds(): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    setContentSize(width: number, height: number): Promise<void>;
+    getContentSize(): Promise<[number, number]>;
+    setMinimumSize(width: number, height: number): Promise<void>;
+    getMinimumSize(): Promise<[number, number]>;
+    setMaximumSize(width: number, height: number): Promise<void>;
+    getMaximumSize(): Promise<[number, number]>;
+    setAspectRatio(aspectRatio: number, extraSize?: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    /** 获取窗口在非最大化/全屏/最小化时的"普通"位置和尺寸。 */
+    getNormalBounds(): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    center(): Promise<void>;
+    moveTop(): Promise<void>;
+    /** mediaSourceId 由 Electron getMediaSourceId 提供；通常在同 Brick 多窗口间使用。 */
+    moveAbove(mediaSourceId: string): Promise<void>;
+    setFullScreen(flag: boolean): Promise<void>;
+    isFullScreen(): Promise<boolean>;
+    isNormal(): Promise<boolean>;
+    isModal(): Promise<boolean>;
+    /** 强制销毁窗口（不触发 close 事件），等价于 BrowserWindow.destroy()。慎用。 */
+    destroy(): Promise<void>;
+    isResizable(): Promise<boolean>;
+    isMovable(): Promise<boolean>;
+    isFocusable(): Promise<boolean>;
+    setMinimizable(flag: boolean): Promise<void>;
+    isMinimizable(): Promise<boolean>;
+    setMaximizable(flag: boolean): Promise<void>;
+    isMaximizable(): Promise<boolean>;
+    setClosable(flag: boolean): Promise<void>;
+    isClosable(): Promise<boolean>;
+    setFullScreenable(flag: boolean): Promise<void>;
+    isFullScreenable(): Promise<boolean>;
+    setEnabled(enabled: boolean): Promise<void>;
+    isEnabled(): Promise<boolean>;
+    hasShadow(): Promise<boolean>;
+    isVisibleOnAllWorkspaces(): Promise<boolean>;
+    setKiosk(flag: boolean): Promise<void>;
+    isKiosk(): Promise<boolean>;
+    flashFrame(flag: boolean): Promise<void>;
+    /**
+     * 任务栏进度条。progress：[0,1] 显示进度；-1 关闭；>1 不确定。
+     * options.mode: 'none' | 'normal' | 'indeterminate' | 'error' | 'paused'。
+     */
+    setProgressBar(progress: number, options?: {
+        mode?: 'none' | 'normal' | 'indeterminate' | 'error' | 'paused';
+    }): Promise<void>;
+    setMenuBarVisibility(visible: boolean): Promise<void>;
+    isMenuBarVisible(): Promise<boolean>;
+    setAutoHideMenuBar(hide: boolean): Promise<void>;
+    isMenuBarAutoHide(): Promise<boolean>;
+    removeMenu(): Promise<void>;
+    /** macOS 透明窗口在内容大小变化后需手动失效阴影。 */
+    invalidateShadow(): Promise<void>;
+    setRepresentedFilename(path: string): Promise<void>;
+    getRepresentedFilename(): Promise<string>;
+    setDocumentEdited(edited: boolean): Promise<void>;
+    isDocumentEdited(): Promise<boolean>;
+    /**
+     * 类 Electron 风格的 webContents 子对象。等价于直接调用 `webContentsSend` 等方法，
+     * 但写法更接近 uTools / Electron 原生：`win.webContents.send('ch', payload)`。
+     */
+    readonly webContents: {
+        send: (channel: string, ...args: unknown[]) => Promise<void>;
+        executeJavaScript: (code: string, userGesture?: boolean) => Promise<unknown>;
+        openDevTools: (options?: {
+            mode?: "left" | "right" | "bottom" | "undocked" | "detach";
+        }) => Promise<void>;
+        closeDevTools: () => Promise<void>;
+        toggleDevTools: () => Promise<void>;
+        isDevToolsOpened: () => Promise<boolean>;
+        goBack: () => Promise<void>;
+        goForward: () => Promise<void>;
+        canGoBack: () => Promise<boolean>;
+        canGoForward: () => Promise<boolean>;
+        getURL: () => Promise<string>;
+        getTitle: () => Promise<string>;
+        setZoomFactor: (factor: number) => Promise<void>;
+        getZoomFactor: () => Promise<number>;
+        setZoomLevel: (level: number) => Promise<void>;
+        getZoomLevel: () => Promise<number>;
+        copy: () => Promise<void>;
+        paste: () => Promise<void>;
+        cut: () => Promise<void>;
+        selectAll: () => Promise<void>;
+        undo: () => Promise<void>;
+        redo: () => Promise<void>;
+    };
+    /** webContents.send 旧别名，保留向后兼容。新代码请用 `win.webContents.send(...)`。 */
+    webContentsSend(channel: string, ...args: unknown[]): Promise<void>;
+    /** 关闭窗口（不可逆）。走 host.ui.closeWindow，而非白名单 close 方法。 */
+    close(): Promise<void>;
+    /** 内部：由 BricklyRuntime 在收到对应 window.* 事件时调用。 */
+    _emit(eventName: string, payload: unknown): void;
+}
+export interface BricklyRuntimeOptions extends BppTransportOptions {
+    /** 协议版本；默认 SDK 内置 PROTOCOL_VERSION。 */
+    protocolVersion?: string;
+}
+/**
+ * Brick SDK 主入口。典型用法：
+ *
+ *   const brick = new BricklyRuntime({ brickId: 'com.example.foo' })
+ *   brick.onCommand('do-it', async (ctx, input) => { ... })
+ *   brick.onReady(async () => { ... })
+ *   brick.start()
+ */
+export declare class BricklyRuntime {
+    readonly brickId: string;
+    readonly transport: BppTransport;
+    private readonly protocolVersion;
+    private readonly commandHandlers;
+    private readonly cancelHandlers;
+    private readonly cancelled;
+    private readonly eventListeners;
+    private readonly windows;
+    private readyHandler?;
+    private shutdownHandler?;
+    private config;
+    private started;
+    private exiting;
+    private hostPidWatchdog?;
+    constructor(opts: BricklyRuntimeOptions);
+    /** 注册 command 处理器。 */
+    onCommand(commandId: string, handler: CommandHandler): this;
+    /** 注册 runtime.ready 之后立即执行的钩子（适合 host-start service 或实例初始化逻辑）。 */
+    onReady(handler: () => unknown | Promise<unknown>): this;
+    /** 注册 runtime.shutdown 处理逻辑；返回后 SDK 自动发送 runtime.bye 并退出。 */
+    onShutdown(handler: () => unknown | Promise<unknown>): this;
+    /** 子窗口 / UI API。 */
+    readonly ui: UiApi;
+    /** 事件订阅 API。 */
+    readonly events: EventsApi;
+    /** 宿主平台能力 API。 */
+    readonly platform: PlatformApi;
+    /** 启动 stdin 循环。 */
+    start(): this;
+    /** 停止 stdin 循环（一般不需要主动调，runtime.shutdown 会自动处理）。 */
+    stop(): void;
+    /** 跨 Brick 调用命令。宿主会自动管理目标 Brick 实例生命周期。 */
+    invoke<T = unknown, TBrickId extends string = string, TCommandId extends string = string>(brickId: TBrickId, commandId: TCommandId, input?: InvokeInput<TBrickId, TCommandId>, options?: InvokeOptions): Promise<InvokeReturn<TBrickId, TCommandId, T>>;
+    invokeRoot<T = unknown, TBrickId extends string = string, TCommandId extends string = string>(brickId: TBrickId, commandId: TCommandId, input?: InvokeInput<TBrickId, TCommandId>, options?: InvokeOptions): Promise<InvokeReturn<TBrickId, TCommandId, T>>;
+    invokeStream<TBrickId extends string = string, TCommandId extends string = string>(brickId: TBrickId, commandId: TCommandId, input?: InvokeInput<TBrickId, TCommandId>, options?: InvokeOptions): AsyncIterable<HostInvokeStreamEvent>;
+    private hostInvokeStream;
+    openSession<TBrickId extends string = string>(brickId: TBrickId, options?: SessionOptions): Promise<BrickSession<TBrickId>>;
+    private handleHello;
+    private handleCommand;
+    private handleEvent;
+    private handleShutdown;
+    private handleHostDisconnect;
+    private startHostPidWatchdog;
+    private buildContext;
+}
+export {};