@syllm/brickly-sdk 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+import type { BridgeErrorCode, BridgeErrorPayload } from './protocol';
+/** SDK 内统一错误类型；toJSON 直接产出 BPP host.error / command.error 的 error 字段。 */
+export declare class BppError extends Error {
+    readonly code: BridgeErrorCode;
+    readonly details?: unknown;
+    constructor(code: BridgeErrorCode, message: string, details?: unknown);
+    toJSON(): BridgeErrorPayload;
+    static from(err: unknown): BppError;
+}
+/** 将 host.error / command.error 中的 error 字段还原为 BppError 实例。 */
+export declare function payloadToError(payload: BridgeErrorPayload): BppError;

package/dist/errors.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BppError = void 0;
+exports.payloadToError = payloadToError;
+/** SDK 内统一错误类型；toJSON 直接产出 BPP host.error / command.error 的 error 字段。 */
+class BppError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'BppError';
+        this.code = code;
+        this.details = details;
+    }
+    toJSON() {
+        return { code: this.code, message: this.message, details: this.details };
+    }
+    static from(err) {
+        if (err instanceof BppError)
+            return err;
+        if (isBridgeErrorPayload(err))
+            return payloadToError(err);
+        if (err instanceof Error)
+            return new BppError('INTERNAL_ERROR', err.message);
+        return new BppError('INTERNAL_ERROR', formatUnknownError(err));
+    }
+}
+exports.BppError = BppError;
+/** 将 host.error / command.error 中的 error 字段还原为 BppError 实例。 */
+function payloadToError(payload) {
+    return new BppError(payload.code, payload.message, payload.details);
+}
+function isBridgeErrorPayload(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const record = value;
+    return typeof record.code === 'string' && typeof record.message === 'string';
+}
+function formatUnknownError(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value === undefined)
+        return 'undefined';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'object') {
+        return stringifyErrorObject(value) ?? String(value);
+    }
+    return String(value);
+}
+function stringifyErrorObject(value) {
+    const seen = new WeakSet();
+    try {
+        return JSON.stringify(value, (_key, item) => {
+            if (typeof item === 'bigint')
+                return item.toString();
+            if (!item || typeof item !== 'object')
+                return item;
+            if (seen.has(item))
+                return '[Circular]';
+            seen.add(item);
+            return item;
+        });
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { BricklyRuntime, BrickSession, WindowHandle } from './api';
+export type { BricklyRuntimeOptions, CommandMap, CommandContext, CommandHandler, EventEnvelope, EventsApi, InvokeOptions, PlatformApi, SessionOptions, UiApi } from './api';
+export { BppTransport } from './runtime';
+export type { BppTransportOptions } from './runtime';
+export { BppError, payloadToError } from './errors';
+export { PROTOCOL_VERSION, type BppMessage, type BppMessageType, type BridgeErrorCode, type BridgeErrorPayload, type BrickUiWindowOptions, type BrickWindowMethod, type CommandInvocationContext, type HostResourceRegisterPayload, type PlatformSystemPathName } from './protocol';
+export { generateDependencyTypes } from './typegen';
+export type { TypegenOptions, TypegenResult } from './typegen';

package/dist/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDependencyTypes = exports.PROTOCOL_VERSION = exports.payloadToError = exports.BppError = exports.BppTransport = exports.WindowHandle = exports.BrickSession = exports.BricklyRuntime = void 0;
+var api_1 = require("./api");
+Object.defineProperty(exports, "BricklyRuntime", { enumerable: true, get: function () { return api_1.BricklyRuntime; } });
+Object.defineProperty(exports, "BrickSession", { enumerable: true, get: function () { return api_1.BrickSession; } });
+Object.defineProperty(exports, "WindowHandle", { enumerable: true, get: function () { return api_1.WindowHandle; } });
+var runtime_1 = require("./runtime");
+Object.defineProperty(exports, "BppTransport", { enumerable: true, get: function () { return runtime_1.BppTransport; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "BppError", { enumerable: true, get: function () { return errors_1.BppError; } });
+Object.defineProperty(exports, "payloadToError", { enumerable: true, get: function () { return errors_1.payloadToError; } });
+var protocol_1 = require("./protocol");
+Object.defineProperty(exports, "PROTOCOL_VERSION", { enumerable: true, get: function () { return protocol_1.PROTOCOL_VERSION; } });
+var typegen_1 = require("./typegen");
+Object.defineProperty(exports, "generateDependencyTypes", { enumerable: true, get: function () { return typegen_1.generateDependencyTypes; } });

package/dist/protocol.d.ts

@@ -0,0 +1,530 @@
+/**
+ * BPP（Brickly Brick Protocol）消息类型定义。
+ *
+ * 本文件是 Brickly/src/main/protocol/types.ts 的镜像，独立于 Electron 主进程代码
+ * 以保持 SDK 零依赖。**协议的真相源是** specs/bpp.schema.json，所有改动都应先改
+ * schema 再同步本文件，且需通过 Brickly/scripts/check-bpp-schema.mjs 校验。
+ */
+export declare const PROTOCOL_VERSION = "0.1.0";
+export type BridgeErrorCode = 'INVALID_INPUT' | 'BRICK_NOT_FOUND' | 'COMMAND_NOT_FOUND' | 'STARTUP_TIMEOUT' | 'PROTOCOL_ERROR' | 'PROCESS_EXITED' | 'CANCELLED' | 'INTERNAL_ERROR' | 'RESOURCE_LIMIT_EXCEEDED' | 'PERMISSION_DENIED' | 'PAYLOAD_TOO_LARGE' | 'RESOURCE_NOT_FOUND' | 'RESOURCE_EXPIRED' | 'DEPENDENCY_NOT_DECLARED' | 'DEPENDENCY_COMMAND_NOT_ALLOWED' | 'PARENT_INVOCATION_REQUIRED' | 'SCREENSHOT_CANCELLED' | 'SCREENSHOT_FAILED' | 'INPUT_FAILED' | 'SYSTEM_FAILED' | 'CURRENT_FOLDER_UNAVAILABLE' | (string & {});
+export interface BridgeErrorPayload {
+    code: BridgeErrorCode;
+    message: string;
+    details?: unknown;
+}
+export interface HostResourceRegisterPayload {
+    mimeType?: string;
+    size?: number;
+    name?: string;
+    ttlMs?: number;
+    content?: unknown;
+    filePath?: string;
+}
+export interface CommandInvocationContext {
+    source: 'unknown' | 'hotkey';
+    triggerId?: string;
+    hotkeyId?: string;
+    binding?: unknown;
+    profileId?: string;
+    dependencyProfiles?: Record<string, string>;
+}
+export interface PlatformScreenshotRegionOptions {
+    outputPath?: string;
+    timeoutMs?: number;
+}
+export interface PlatformScreenshotResult {
+    path: string;
+    mimeType: 'image/png';
+    size: number;
+    createdAt: number;
+}
+export interface PlatformInputKeyboardTapPayload {
+    key: string;
+    modifiers?: string[];
+}
+export interface PlatformInputMousePointPayload {
+    x: number;
+    y: number;
+}
+export type PlatformClipboardKind = 'text' | 'file' | 'image';
+export interface PlatformClipboardReadResult {
+    kind?: PlatformClipboardKind;
+    mimeType?: string;
+    size?: number;
+    hash?: string;
+    textPreview?: string;
+    text?: string;
+    sourceType?: string;
+    name?: string;
+    path?: string;
+    paths?: string[];
+    width?: number;
+    height?: number;
+    resource?: HostResourceRegisterPayload;
+    capturedAt: number;
+}
+export type PlatformClipboardContent = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'html';
+    html: string;
+} | {
+    kind: 'rtf';
+    rtf: string;
+} | {
+    kind: 'image';
+    path: string;
+} | {
+    kind: 'image';
+    dataUrl: string;
+} | {
+    kind: 'image';
+    base64: string;
+    mimeType?: string;
+} | {
+    kind: 'image';
+    bytes: ArrayBuffer | Uint8Array | number[];
+    mimeType?: string;
+} | {
+    kind: 'file';
+    paths: string[];
+};
+export interface PlatformClipboardSetResult {
+    kind: PlatformClipboardKind | 'html' | 'rtf' | 'empty';
+    formats: string[];
+    updatedAt: number;
+    paths?: string[];
+    names?: string[];
+    width?: number;
+    height?: number;
+}
+export interface PlatformScreenPoint {
+    x: number;
+    y: number;
+}
+export interface PlatformScreenRect extends PlatformScreenPoint {
+    width: number;
+    height: number;
+}
+export interface PlatformScreenDisplay {
+    id: number;
+    label: string;
+    bounds: PlatformScreenRect;
+    workArea: PlatformScreenRect;
+    size: {
+        width: number;
+        height: number;
+    };
+    workAreaSize: {
+        width: number;
+        height: number;
+    };
+    scaleFactor: number;
+    rotation: number;
+    colorDepth: number;
+    colorSpace: string;
+    depthPerComponent: number;
+    displayFrequency: number;
+    internal: boolean;
+    monochrome: boolean;
+    detected: boolean;
+    maximumCursorSize: {
+        width: number;
+        height: number;
+    };
+    touchSupport: 'available' | 'unavailable' | 'unknown';
+    accelerometerSupport: 'available' | 'unavailable' | 'unknown';
+    nativeOrigin: PlatformScreenPoint;
+}
+export interface PlatformScreenCaptureOptions extends PlatformScreenshotRegionOptions {
+    format?: 'dataUrl' | 'file';
+}
+export type PlatformScreenCaptureResult = {
+    dataUrl: string;
+    mimeType: 'image/png';
+    size: number;
+    createdAt: number;
+} | PlatformScreenshotResult;
+export interface PlatformScreenColorPickOptions {
+    timeoutMs?: number;
+}
+export interface PlatformScreenColorPickResult {
+    hex: string;
+    rgb: string;
+}
+export interface PlatformScreenDesktopCaptureOptions {
+    types: Array<'screen' | 'window'>;
+    thumbnailSize?: {
+        width: number;
+        height: number;
+    };
+    fetchWindowIcons?: boolean;
+}
+export interface PlatformScreenDesktopCaptureSource {
+    id: string;
+    name: string;
+    displayId: string;
+    thumbnail?: string;
+    appIcon?: string;
+}
+export type PlatformSystemPathName = 'home' | 'appData' | 'assets' | 'userData' | 'sessionData' | 'temp' | 'exe' | 'module' | 'desktop' | 'documents' | 'downloads' | 'music' | 'pictures' | 'videos' | 'recent' | 'logs' | 'crashDumps';
+/** host.ui.createBrowserWindow options 白名单（仅 SDK 直接转发）。 */
+export interface BrickUiWindowOptions {
+    width?: number;
+    height?: number;
+    x?: number;
+    y?: number;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    frame?: boolean;
+    transparent?: boolean;
+    alwaysOnTop?: boolean;
+    resizable?: boolean;
+    movable?: boolean;
+    focusable?: boolean;
+    skipTaskbar?: boolean;
+    hasShadow?: boolean;
+    opacity?: number;
+    show?: boolean;
+    title?: string;
+    closable?: boolean;
+    kiosk?: boolean;
+    fullscreen?: boolean;
+    fullscreenable?: boolean;
+    minimizable?: boolean;
+    maximizable?: boolean;
+    backgroundColor?: string;
+    autoHideMenuBar?: boolean;
+    thickFrame?: boolean;
+    roundedCorners?: boolean;
+    enableLargerThanScreen?: boolean;
+    webPreferences?: {
+        preload?: string;
+        devTools?: boolean;
+        webviewTag?: boolean;
+    };
+    network?: BrickWindowNetworkOptions;
+}
+export interface BrickWindowNetworkOptions {
+    enabled?: boolean;
+    captureBody?: boolean;
+    maxBodyChars?: number;
+    maxPostDataSize?: number;
+    maxTotalBufferSize?: number;
+    maxResourceBufferSize?: number;
+    includeExtraInfo?: boolean;
+    targets?: 'window' | 'webview' | 'all';
+}
+export interface BrickWindowNetworkEvent {
+    windowId: number;
+    webContentsId: number;
+    targetWebContentsId: number;
+    source: 'cdp';
+    stage: 'debugger-attached' | 'debugger-detached' | 'debugger-attach-error' | 'request' | 'request-extra-info' | 'response' | 'response-extra-info' | 'redirect-response' | 'loading-finished' | 'loading-failed' | 'response-body' | 'response-body-error';
+    capturedAt: number;
+    cdpRequestId?: string;
+    url?: string;
+    method?: string;
+    resourceType?: string;
+    statusCode?: number;
+    statusText?: string;
+    mimeType?: string;
+    requestHeaders?: Record<string, string | string[] | null>;
+    responseHeaders?: Record<string, string | string[] | null>;
+    request?: unknown;
+    response?: unknown;
+    body?: string;
+    bodyLength?: number;
+    base64Encoded?: boolean;
+    truncated?: boolean;
+    omittedChars?: number;
+    error?: string;
+    details?: unknown;
+    [key: string]: unknown;
+}
+/** host.ui.callWindow 方法白名单。 */
+export type BrickWindowMethod = 'setBounds' | 'getBounds' | 'setPosition' | 'getPosition' | 'setSize' | 'getSize' | 'setOpacity' | 'getOpacity' | 'setAlwaysOnTop' | 'isAlwaysOnTop' | 'setIgnoreMouseEvents' | 'setSkipTaskbar' | 'setTitle' | 'getTitle' | 'setResizable' | 'setMovable' | 'setFocusable' | 'setHasShadow' | 'setBackgroundColor' | 'setVisibleOnAllWorkspaces' | 'minimize' | 'maximize' | 'unmaximize' | 'restore' | 'hide' | 'show' | 'showInactive' | 'focus' | 'blur' | 'close' | 'isDestroyed' | 'isVisible' | 'isFocused' | 'isMinimized' | 'isMaximized' | 'loadURL' | 'loadFile' | 'reload' | 'webContents.send' | 'webContents.executeJavaScript' | 'webContents.openDevTools' | 'webContents.closeDevTools' | 'setContentBounds' | 'getContentBounds' | 'setContentSize' | 'getContentSize' | 'setMinimumSize' | 'getMinimumSize' | 'setMaximumSize' | 'getMaximumSize' | 'setAspectRatio' | 'center' | 'moveTop' | 'moveAbove' | 'setFullScreen' | 'isFullScreen' | 'isNormal' | 'isModal' | 'destroy' | 'getNormalBounds' | 'isResizable' | 'isMovable' | 'isFocusable' | 'setMinimizable' | 'isMinimizable' | 'setMaximizable' | 'isMaximizable' | 'setClosable' | 'isClosable' | 'setFullScreenable' | 'isFullScreenable' | 'setEnabled' | 'isEnabled' | 'hasShadow' | 'isVisibleOnAllWorkspaces' | 'setKiosk' | 'isKiosk' | 'flashFrame' | 'setProgressBar' | 'setMenuBarVisibility' | 'isMenuBarVisible' | 'setAutoHideMenuBar' | 'isMenuBarAutoHide' | 'removeMenu' | 'invalidateShadow' | 'setRepresentedFilename' | 'getRepresentedFilename' | 'setDocumentEdited' | 'isDocumentEdited' | 'webContents.toggleDevTools' | 'webContents.isDevToolsOpened' | 'webContents.goBack' | 'webContents.goForward' | 'webContents.canGoBack' | 'webContents.canGoForward' | 'webContents.getURL' | 'webContents.getTitle' | 'webContents.setZoomFactor' | 'webContents.getZoomFactor' | 'webContents.setZoomLevel' | 'webContents.getZoomLevel' | 'webContents.copy' | 'webContents.paste' | 'webContents.cut' | 'webContents.selectAll' | 'webContents.undo' | 'webContents.redo';
+export type BppMessage = {
+    type: 'host.hello';
+    protocolVersion: string;
+    config?: Record<string, unknown>;
+} | {
+    type: 'runtime.ready';
+    protocolVersion: string;
+    brickId?: string;
+} | {
+    type: 'runtime.ping';
+    id: string;
+} | {
+    type: 'runtime.pong';
+    id: string;
+} | {
+    type: 'event.notify';
+    event: string;
+    payload?: unknown;
+    sourceBrickId: string;
+    publishedAt: number;
+} | {
+    type: 'host.event.publish';
+    id: string;
+    event: string;
+    payload?: unknown;
+} | {
+    type: 'host.resource.register';
+    id: string;
+    resource: HostResourceRegisterPayload;
+} | {
+    type: 'host.resource.get';
+    id: string;
+    resourceId: string;
+} | {
+    type: 'host.invoke';
+    id: string;
+    brickId: string;
+    commandId: string;
+    input: unknown;
+    parentRequestId: string;
+    profileId?: string;
+    stream?: boolean;
+} | {
+    type: 'host.invokeRoot';
+    id: string;
+    brickId: string;
+    commandId: string;
+    input: unknown;
+    profileId?: string;
+} | {
+    type: 'host.invoke.progress';
+    id: string;
+    progress: number;
+    message?: string;
+} | {
+    type: 'host.invoke.chunk';
+    id: string;
+    name?: string;
+    chunk: unknown;
+} | {
+    type: 'host.invoke.output';
+    id: string;
+    name: string;
+    value: unknown;
+} | {
+    type: 'host.session.open';
+    id: string;
+    brickId: string;
+    profileId?: string;
+} | {
+    type: 'host.session.invoke';
+    id: string;
+    sessionId: string;
+    commandId: string;
+    input: unknown;
+    parentRequestId: string;
+} | {
+    type: 'host.session.close';
+    id: string;
+    sessionId: string;
+} | {
+    type: 'host.result';
+    id: string;
+    result?: unknown;
+} | {
+    type: 'host.error';
+    id: string;
+    error: BridgeErrorPayload;
+} | {
+    type: 'command.invoke';
+    id: string;
+    commandId: string;
+    input: unknown;
+    invocation?: CommandInvocationContext;
+} | {
+    type: 'command.cancel';
+    id: string;
+} | {
+    type: 'command.progress';
+    id: string;
+    progress: number;
+    message?: string;
+} | {
+    type: 'command.chunk';
+    id: string;
+    name?: string;
+    chunk: unknown;
+} | {
+    type: 'command.output';
+    id: string;
+    name: string;
+    value: unknown;
+} | {
+    type: 'command.result';
+    id: string;
+    result?: unknown;
+} | {
+    type: 'command.error';
+    id: string;
+    error: BridgeErrorPayload;
+} | {
+    type: 'host.ui.createBrowserWindow';
+    id: string;
+    url: string;
+    options?: BrickUiWindowOptions;
+    parentWindowId?: number;
+} | {
+    type: 'host.ui.callWindow';
+    id: string;
+    windowId: number;
+    method: BrickWindowMethod;
+    args?: unknown[];
+    parentRequestId?: string;
+} | {
+    type: 'host.ui.closeWindow';
+    id: string;
+    windowId: number;
+} | {
+    type: 'host.ui.listWindows';
+    id: string;
+} | {
+    type: 'host.platform.input.keyboardTap';
+    id: string;
+    payload: PlatformInputKeyboardTapPayload;
+} | {
+    type: 'host.platform.input.mouseMove';
+    id: string;
+    payload: PlatformInputMousePointPayload;
+} | {
+    type: 'host.platform.input.mouseClick';
+    id: string;
+    payload: PlatformInputMousePointPayload;
+} | {
+    type: 'host.platform.input.mouseDoubleClick';
+    id: string;
+    payload: PlatformInputMousePointPayload;
+} | {
+    type: 'host.platform.input.mouseRightClick';
+    id: string;
+    payload: PlatformInputMousePointPayload;
+} | {
+    type: 'host.platform.clipboard.readContent';
+    id: string;
+} | {
+    type: 'host.platform.clipboard.setContent';
+    id: string;
+    content: PlatformClipboardContent;
+} | {
+    type: 'host.platform.screenshot.selectRegion';
+    id: string;
+    options?: PlatformScreenshotRegionOptions;
+} | {
+    type: 'host.platform.screen.captureRegion';
+    id: string;
+    options?: PlatformScreenCaptureOptions;
+} | {
+    type: 'host.platform.screen.pickColor';
+    id: string;
+    options?: PlatformScreenColorPickOptions;
+} | {
+    type: 'host.platform.screen.getPrimaryDisplay';
+    id: string;
+} | {
+    type: 'host.platform.screen.getAllDisplays';
+    id: string;
+} | {
+    type: 'host.platform.screen.getCursorScreenPoint';
+    id: string;
+} | {
+    type: 'host.platform.screen.getDisplayNearestPoint';
+    id: string;
+    point: PlatformScreenPoint;
+} | {
+    type: 'host.platform.screen.getDisplayMatching';
+    id: string;
+    rect: PlatformScreenRect;
+} | {
+    type: 'host.platform.screen.screenToDipPoint';
+    id: string;
+    point: PlatformScreenPoint;
+} | {
+    type: 'host.platform.screen.dipToScreenPoint';
+    id: string;
+    point: PlatformScreenPoint;
+} | {
+    type: 'host.platform.screen.screenToDipRect';
+    id: string;
+    rect: PlatformScreenRect;
+} | {
+    type: 'host.platform.screen.dipToScreenRect';
+    id: string;
+    rect: PlatformScreenRect;
+} | {
+    type: 'host.platform.screen.desktopCaptureSources';
+    id: string;
+    options: PlatformScreenDesktopCaptureOptions;
+} | {
+    type: 'host.platform.system.showNotification';
+    id: string;
+    body: string;
+    clickFeatureCode?: string;
+} | {
+    type: 'host.platform.system.shellOpenPath';
+    id: string;
+    fullPath: string;
+} | {
+    type: 'host.platform.system.shellTrashItem';
+    id: string;
+    fullPath: string;
+} | {
+    type: 'host.platform.system.shellShowItemInFolder';
+    id: string;
+    fullPath: string;
+} | {
+    type: 'host.platform.system.shellOpenExternal';
+    id: string;
+    url: string;
+} | {
+    type: 'host.platform.system.shellBeep';
+    id: string;
+} | {
+    type: 'host.platform.system.getNativeId';
+    id: string;
+} | {
+    type: 'host.platform.system.getAppName';
+    id: string;
+} | {
+    type: 'host.platform.system.getAppVersion';
+    id: string;
+} | {
+    type: 'host.platform.system.getPath';
+    id: string;
+    name: PlatformSystemPathName;
+} | {
+    type: 'host.platform.system.getFileIcon';
+    id: string;
+    filePath: string;
+} | {
+    type: 'host.platform.system.readCurrentFolderPath';
+    id: string;
+} | {
+    type: 'host.platform.system.readCurrentBrowserUrl';
+    id: string;
+} | {
+    type: 'host.platform.system.isDev';
+    id: string;
+} | {
+    type: 'host.platform.system.isMacOS';
+    id: string;
+} | {
+    type: 'host.platform.system.isWindows';
+    id: string;
+} | {
+    type: 'host.platform.system.isLinux';
+    id: string;
+} | {
+    type: 'runtime.shutdown';
+} | {
+    type: 'runtime.bye';
+};
+export type BppMessageType = BppMessage['type'];

package/dist/protocol.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * BPP（Brickly Brick Protocol）消息类型定义。
+ *
+ * 本文件是 Brickly/src/main/protocol/types.ts 的镜像，独立于 Electron 主进程代码
+ * 以保持 SDK 零依赖。**协议的真相源是** specs/bpp.schema.json，所有改动都应先改
+ * schema 再同步本文件，且需通过 Brickly/scripts/check-bpp-schema.mjs 校验。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOL_VERSION = void 0;
+exports.PROTOCOL_VERSION = '0.1.0';