@bctrl/sdk 1.0.1

package/dist/drivers/desktop/session.js

@@ -0,0 +1,432 @@
+/**
+ * DesktopSession - SDK client for desktop automation
+ *
+ * Provides namespaced APIs for mouse, keyboard, screen, and window control.
+ * Can also launch browsers for DOM-level control via Playwright.
+ */
+import { fetchWithTimeout, parseJsonResponse, DEFAULT_TIMEOUT_MS, LONG_TIMEOUT_MS, } from '../../utils/http.js';
+export class DesktopSession {
+    id;
+    baseUrl;
+    apiKey;
+    _mouse;
+    _keyboard;
+    _screen;
+    _window;
+    _clipboard;
+    _cua;
+    constructor(sessionId, baseUrl, options) {
+        this.id = sessionId;
+        this.baseUrl = baseUrl;
+        this.apiKey = options?.apiKey;
+        this._mouse = new DesktopMouse(this);
+        this._keyboard = new DesktopKeyboard(this);
+        this._screen = new DesktopScreen(this);
+        this._window = new DesktopWindow(this);
+        this._clipboard = new DesktopClipboard(this);
+        this._cua = new DesktopCua(this);
+    }
+    /** Mouse control (move, click, drag, scroll) */
+    get mouse() {
+        return this._mouse;
+    }
+    /** Keyboard control (type, press, hotkey) */
+    get keyboard() {
+        return this._keyboard;
+    }
+    /** Screen capture and display info */
+    get screen() {
+        return this._screen;
+    }
+    /** Window management (list, focus, resize) */
+    get window() {
+        return this._window;
+    }
+    /** Clipboard read/write */
+    get clipboard() {
+        return this._clipboard;
+    }
+    /**
+     * CUA (Computer Use Agent) - AI-powered desktop automation.
+     * Similar to Stagehand for browser automation.
+     */
+    get cua() {
+        return this._cua;
+    }
+    /**
+     * Launch a browser that can be controlled via Playwright-style API.
+     * The browser runs on the desktop agent's machine.
+     *
+     * @param options - Browser launch options
+     * @returns Browser launch result with session, context, and page IDs
+     *
+     * @example
+     * ```ts
+     * const browser = await desktop.launchBrowser({ headless: false });
+     * // Use browser.sessionId, browser.defaultContextId, browser.defaultPageId
+     * ```
+     */
+    async launchBrowser(options) {
+        return this.rpc('browser.launch', [options]);
+    }
+    /**
+     * Close a launched browser.
+     */
+    async closeBrowser() {
+        await this.rpc('browser.close', []);
+    }
+    /**
+     * Check if a browser is running.
+     */
+    async isBrowserRunning() {
+        return this.rpc('browser.isRunning', []);
+    }
+    /**
+     * Close the desktop session and clean up resources.
+     */
+    async close() {
+        const headers = {};
+        if (this.apiKey) {
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        }
+        const response = await fetchWithTimeout(`${this.baseUrl}/desktop/sessions/${this.id}`, { method: 'DELETE', headers }, DEFAULT_TIMEOUT_MS);
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Failed to close desktop session ${this.id}: HTTP ${response.status} - ${text}`);
+        }
+    }
+    /**
+     * Send an RPC call to the desktop agent.
+     * @internal
+     */
+    async rpc(method, args, target = 'desktop') {
+        // CUA operations can be slow (AI processing)
+        const timeout = target === 'cua' ? LONG_TIMEOUT_MS : DEFAULT_TIMEOUT_MS;
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (this.apiKey) {
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        }
+        const response = await fetchWithTimeout(`${this.baseUrl}/desktop/cmd`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                sessionId: this.id,
+                target,
+                method,
+                args,
+            }),
+        }, timeout);
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Desktop RPC failed: target=${target}, method=${method}, sessionId=${this.id}, ` +
+                `status=${response.status}, message=${text}`);
+        }
+        return parseJsonResponse(response, `${target} RPC ${method} (session: ${this.id})`);
+    }
+}
+// ============================================================================
+// Namespace Classes (exported for type access)
+// ============================================================================
+/**
+ * Mouse control for desktop automation.
+ * Provides move, click, drag, and scroll operations.
+ */
+export class DesktopMouse {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    /**
+     * Move the mouse to the specified coordinates.
+     * @param x - Horizontal position in pixels (0 = left edge of screen)
+     * @param y - Vertical position in pixels (0 = top edge of screen)
+     */
+    async move(x, y) {
+        await this.session.rpc('mouse.move', [x, y]);
+    }
+    /**
+     * Click at the current mouse position.
+     * @param button - Which mouse button to click (default: 'left')
+     */
+    async click(button = 'left') {
+        await this.session.rpc('mouse.click', [button]);
+    }
+    /**
+     * Double-click at the current mouse position.
+     */
+    async doubleClick() {
+        await this.session.rpc('mouse.doubleClick', []);
+    }
+    /**
+     * Drag from one position to another.
+     * @param fromX - Starting horizontal position
+     * @param fromY - Starting vertical position
+     * @param toX - Ending horizontal position
+     * @param toY - Ending vertical position
+     */
+    async drag(fromX, fromY, toX, toY) {
+        await this.session.rpc('mouse.drag', [fromX, fromY, toX, toY]);
+    }
+    /**
+     * Scroll at the current mouse position.
+     * Positive values scroll down/right, negative scroll up/left.
+     * @param deltaX - Horizontal scroll amount in pixels
+     * @param deltaY - Vertical scroll amount in pixels
+     */
+    async scroll(deltaX, deltaY) {
+        await this.session.rpc('mouse.scroll', [deltaX, deltaY]);
+    }
+    /**
+     * Get the current mouse position.
+     * @returns Object with x and y coordinates in pixels
+     */
+    async position() {
+        return this.session.rpc('mouse.position', []);
+    }
+}
+/**
+ * Keyboard control for desktop automation.
+ * Provides typing, key presses, and hotkey combinations.
+ */
+export class DesktopKeyboard {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    /**
+     * Type a string of text.
+     * @param text - Text to type
+     */
+    async type(text) {
+        await this.session.rpc('keyboard.type', [text]);
+    }
+    /**
+     * Press a single key.
+     * @param key - Key to press (e.g., 'Enter', 'Tab', 'a')
+     */
+    async press(key) {
+        await this.session.rpc('keyboard.press', [key]);
+    }
+    /**
+     * Hold down a key.
+     * @param key - Key to hold down
+     */
+    async down(key) {
+        await this.session.rpc('keyboard.down', [key]);
+    }
+    /**
+     * Release a held key.
+     * @param key - Key to release
+     */
+    async up(key) {
+        await this.session.rpc('keyboard.up', [key]);
+    }
+    /**
+     * Press a hotkey combination.
+     * @param keys - Keys to press together (e.g., 'Ctrl', 'C')
+     *
+     * @example
+     * ```ts
+     * await keyboard.hotkey('Ctrl', 'C'); // Copy
+     * await keyboard.hotkey('Ctrl', 'Shift', 'T'); // Reopen closed tab
+     * ```
+     */
+    async hotkey(...keys) {
+        await this.session.rpc('keyboard.hotkey', [keys]);
+    }
+}
+/**
+ * Screen control for desktop automation.
+ * Provides capture and display information.
+ */
+export class DesktopScreen {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    /**
+     * Capture the screen or a region.
+     * @param region - Optional region to capture
+     * @returns PNG image as Buffer
+     */
+    async capture(region) {
+        const base64 = await this.session.rpc('screen.capture', [region]);
+        return Buffer.from(base64, 'base64');
+    }
+    /**
+     * Get the primary screen size.
+     * @returns Screen dimensions in pixels
+     */
+    async size() {
+        return this.session.rpc('screen.size', []);
+    }
+}
+/**
+ * Window management for desktop automation.
+ * Provides listing, focusing, and resizing windows.
+ */
+export class DesktopWindow {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    /**
+     * List all visible windows.
+     * @returns Array of window information
+     */
+    async list() {
+        return this.session.rpc('window.list', []);
+    }
+    /**
+     * Get the currently active (focused) window.
+     * @returns Active window info or null if none
+     */
+    async active() {
+        return this.session.rpc('window.active', []);
+    }
+    /**
+     * Focus a window by handle.
+     * @param handle - Window handle from list()
+     */
+    async focus(handle) {
+        await this.session.rpc('window.focus', [handle]);
+    }
+    /**
+     * Get window bounds.
+     * @param handle - Window handle
+     * @returns Window position and size
+     */
+    async bounds(handle) {
+        return this.session.rpc('window.bounds', [handle]);
+    }
+    /**
+     * Set window bounds.
+     * @param handle - Window handle
+     * @param bounds - Partial bounds to set
+     */
+    async setBounds(handle, bounds) {
+        await this.session.rpc('window.setBounds', [handle, bounds]);
+    }
+    /**
+     * Minimize a window.
+     * @param handle - Window handle
+     */
+    async minimize(handle) {
+        await this.session.rpc('window.minimize', [handle]);
+    }
+    /**
+     * Maximize a window.
+     * @param handle - Window handle
+     */
+    async maximize(handle) {
+        await this.session.rpc('window.maximize', [handle]);
+    }
+    /**
+     * Restore a minimized/maximized window.
+     * @param handle - Window handle
+     */
+    async restore(handle) {
+        await this.session.rpc('window.restore', [handle]);
+    }
+    /**
+     * Close a window.
+     * @param handle - Window handle
+     */
+    async close(handle) {
+        await this.session.rpc('window.close', [handle]);
+    }
+}
+/**
+ * Clipboard operations for desktop automation.
+ */
+export class DesktopClipboard {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    /**
+     * Read text from the clipboard.
+     * @returns Clipboard text content
+     */
+    async read() {
+        return this.session.rpc('clipboard.read', []);
+    }
+    /**
+     * Write text to the clipboard.
+     * @param text - Text to write
+     */
+    async write(text) {
+        await this.session.rpc('clipboard.write', [text]);
+    }
+}
+/**
+ * CUA (Computer Use Agent) - AI-powered desktop automation.
+ *
+ * Similar to Stagehand for browser automation, CUA provides:
+ * - run(): Execute multi-step tasks with AI guidance
+ * - predictClick(): Find elements using vision
+ */
+export class DesktopCua {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    /**
+     * Initialize the CUA agent.
+     * Must be called before using run() or predictClick().
+     *
+     * @param config - Agent configuration
+     *
+     * @example
+     * ```ts
+     * await desktop.cua.init({ model: 'claude-sonnet-4-5-20250929' });
+     * ```
+     */
+    async init(config) {
+        return this.session.rpc('agent.init', [config], 'cua');
+    }
+    /**
+     * Close the CUA agent and clean up resources.
+     */
+    async close() {
+        await this.session.rpc('agent.close', [], 'cua');
+    }
+    /**
+     * Run a computer-use task with AI guidance.
+     *
+     * Like Stagehand's act() but for desktop automation.
+     * The AI will analyze the screen and execute steps to complete the task.
+     *
+     * @param instruction - What task to perform
+     * @param options - Run options
+     *
+     * @example
+     * ```ts
+     * const result = await desktop.cua.run('Open Chrome and navigate to google.com');
+     * console.log(result.steps);
+     * ```
+     */
+    async run(instruction, options) {
+        return this.session.rpc('run', [instruction, options], 'cua');
+    }
+    /**
+     * Predict where to click to accomplish a task.
+     *
+     * Uses vision model to find elements on screen.
+     * Returns coordinates that can be used with mouse.move() and mouse.click().
+     *
+     * @param instruction - What to find on screen
+     *
+     * @example
+     * ```ts
+     * const { x, y } = await desktop.cua.predictClick('the submit button');
+     * await desktop.mouse.move(x, y);
+     * await desktop.mouse.click();
+     * ```
+     */
+    async predictClick(instruction) {
+        return this.session.rpc('predictClick', [instruction], 'cua');
+    }
+}

package/dist/drivers/playwright/event-emitter.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Handler function type for event listeners.
+ */
+export type Handler<T = unknown> = (event: T) => void;
+/**
+ * The EventEmitter class that many Playwright classes extend.
+ *
+ * This provides a familiar event-driven interface for handling browser events
+ * like page load, console messages, dialogs, network requests, etc.
+ *
+ * @example
+ * ```ts
+ * page.on('console', msg => {
+ *   console.log('Page logged:', msg.text());
+ * });
+ *
+ * page.once('load', () => {
+ *   console.log('Page loaded!');
+ * });
+ * ```
+ *
+ * @see https://playwright.dev/docs/api/class-page#events
+ */
+export declare class PlaywrightEventEmitter<Events extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Map of event types to their listeners.
+     * @internal
+     */
+    private _listeners;
+    private notifyFirstListener;
+    private notifyNoListeners;
+    /**
+     * Bind an event listener to fire when an event occurs.
+     *
+     * @param event - The event type to listen for.
+     * @param handler - The function to call when the event occurs.
+     * @returns `this` to allow for method chaining.
+     *
+     * @example
+     * ```ts
+     * page.on('request', request => {
+     *   console.log('Request:', request.url());
+     * });
+     * ```
+     *
+     * @see https://playwright.dev/docs/api/class-page#page-event-request
+     */
+    on<Key extends keyof Events>(event: Key, handler: Handler<Events[Key]>): this;
+    /**
+     * Remove an event listener.
+     *
+     * If `handler` is provided, only that specific listener is removed.
+     * If `handler` is not provided, all listeners for that event type are removed.
+     *
+     * @param event - The event type.
+     * @param handler - Optional specific handler to remove.
+     * @returns `this` to allow for method chaining.
+     *
+     * @example
+     * ```ts
+     * const handler = msg => console.log(msg);
+     * page.on('console', handler);
+     * // Later...
+     * page.off('console', handler);
+     * ```
+     *
+     * @see https://playwright.dev/docs/api/class-page#page-remove-listener
+     */
+    off<Key extends keyof Events>(event: Key, handler?: Handler<Events[Key]>): this;
+    /**
+     * Alias for off() - removes an event listener.
+     *
+     * @see https://playwright.dev/docs/api/class-page#page-remove-listener
+     */
+    removeListener<Key extends keyof Events>(event: Key, handler: Handler<Events[Key]>): this;
+    /**
+     * Bind an event listener that will fire only once.
+     *
+     * After the handler is called once, it is automatically removed.
+     *
+     * @param event - The event type to listen for.
+     * @param handler - The function to call when the event occurs.
+     * @returns `this` to allow for method chaining.
+     *
+     * @example
+     * ```ts
+     * page.once('load', () => {
+     *   console.log('Page loaded for the first time!');
+     * });
+     * ```
+     *
+     * @see https://playwright.dev/docs/api/class-page#page-wait-for-event
+     */
+    once<Key extends keyof Events>(event: Key, handler: Handler<Events[Key]>): this;
+    /**
+     * Alias for on() - adds an event listener.
+     *
+     * @see https://playwright.dev/docs/api/class-page#page-event-console
+     */
+    addListener<Key extends keyof Events>(event: Key, handler: Handler<Events[Key]>): this;
+    /**
+     * Emit an event, calling all registered handlers.
+     *
+     * This method is typically used internally by Playwright classes to dispatch
+     * events. Users rarely need to call this directly.
+     *
+     * @param event - The event type to emit.
+     * @param data - The event data to pass to handlers.
+     * @returns `true` if there were listeners for this event, `false` otherwise.
+     */
+    emit<Key extends keyof Events>(event: Key, data: Events[Key]): boolean;
+    /**
+     * Get the count of listeners for a specific event type.
+     *
+     * @param event - The event type.
+     * @returns The number of registered listeners.
+     *
+     * @example
+     * ```ts
+     * const count = page.listenerCount('request');
+     * console.log(`There are ${count} request listeners`);
+     * ```
+     */
+    listenerCount<Key extends keyof Events>(event: Key): number;
+    /**
+     * Remove all listeners.
+     *
+     * If `event` is provided, only listeners for that event type are removed.
+     * If `event` is not provided, all listeners for all event types are removed.
+     *
+     * @param event - Optional event type to remove listeners for.
+     * @returns `this` to allow for method chaining.
+     *
+     * @example
+     * ```ts
+     * // Remove all 'request' listeners
+     * page.removeAllListeners('request');
+     *
+     * // Remove ALL listeners
+     * page.removeAllListeners();
+     * ```
+     */
+    removeAllListeners<Key extends keyof Events>(event?: Key): this;
+    /**
+     * PrependListener - adds a listener that will be called before other listeners.
+     *
+     * @param event - The event type to listen for.
+     * @param handler - The function to call when the event occurs.
+     * @returns `this` to allow for method chaining.
+     */
+    prependListener<Key extends keyof Events>(event: Key, handler: Handler<Events[Key]>): this;
+    /**
+     * PrependOnceListener - adds a once listener that will be called before other listeners.
+     *
+     * @param event - The event type to listen for.
+     * @param handler - The function to call when the event occurs.
+     * @returns `this` to allow for method chaining.
+     */
+    prependOnceListener<Key extends keyof Events>(event: Key, handler: Handler<Events[Key]>): this;
+}