@bctrl/sdk 1.0.1

package/dist/contracts/vault.js

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+export const VaultSessionPolicySchema = z.object({
+    allow: z.array(z.string().min(1)).optional(),
+    deny: z.array(z.string().min(1)).optional(),
+    allowRawReads: z.boolean().optional(),
+});
+export const VaultAgentDefaultListFilterSchema = z.object({
+    prefix: z.string().min(1).optional(),
+    origin: z.string().min(1).optional(),
+    limit: z.number().int().positive().optional(),
+});
+export const VaultAgentAdapterConfigSchema = z.object({
+    toolPrefix: z.string().min(1).optional(),
+    defaultListFilter: VaultAgentDefaultListFilterSchema.optional(),
+    allowRawReads: z.boolean().optional(),
+});
+function dedupeStrings(values) {
+    if (!values || values.length === 0)
+        return undefined;
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        if (seen.has(value))
+            continue;
+        seen.add(value);
+        out.push(value);
+    }
+    return out.length > 0 ? out : undefined;
+}
+function splitMatchOrigins(matchOrigins) {
+    if (!matchOrigins || matchOrigins.length === 0)
+        return {};
+    const origins = [];
+    const originPatterns = [];
+    for (const entry of matchOrigins) {
+        if (entry.includes('*')) {
+            originPatterns.push(entry);
+        }
+        else {
+            origins.push(entry);
+        }
+    }
+    return {
+        ...(origins.length > 0 ? { origins } : {}),
+        ...(originPatterns.length > 0 ? { originPatterns } : {}),
+    };
+}
+export const VaultCredentialSchema = z.object({
+    label: z.string().optional(),
+    origins: z.array(z.string().min(1)).optional(),
+    originPatterns: z.array(z.string().min(1)).optional(),
+    username: z.string(),
+    password: z.string(),
+    totp: z.string().optional(),
+    notes: z.string().optional(),
+});
+const VaultCredentialInputRawSchema = z.object({
+    label: z.string().optional(),
+    origins: z.array(z.string().min(1)).optional(),
+    originPatterns: z.array(z.string().min(1)).optional(),
+    matchOrigins: z.array(z.string().min(1)).optional(),
+    username: z.string(),
+    password: z.string(),
+    totp: z.string().optional(),
+    notes: z.string().optional(),
+});
+export const VaultCredentialInputSchema = VaultCredentialInputRawSchema.transform((input) => {
+    const split = splitMatchOrigins(input.matchOrigins);
+    const mergedOrigins = dedupeStrings([...(input.origins ?? []), ...(split.origins ?? [])]);
+    const mergedOriginPatterns = dedupeStrings([
+        ...(input.originPatterns ?? []),
+        ...(split.originPatterns ?? []),
+    ]);
+    return {
+        ...(input.label !== undefined ? { label: input.label } : {}),
+        ...(mergedOrigins ? { origins: mergedOrigins } : {}),
+        ...(mergedOriginPatterns ? { originPatterns: mergedOriginPatterns } : {}),
+        username: input.username,
+        password: input.password,
+        ...(input.totp !== undefined ? { totp: input.totp } : {}),
+        ...(input.notes !== undefined ? { notes: input.notes } : {}),
+    };
+});
+export const VaultKeySchema = z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[\w@.-]+(\/[\w@.-]+)*$/, 'Vault key must be alphanumeric segments (allowing @, ., -, _) separated by slashes')
+    .refine((key) => !key.split('/').some((segment) => segment === '..' || segment === '.'), 'Vault key must not contain "." or ".." segments');
+export const VaultCredentialSourceSchema = z.enum(['native', '1password']);
+export const VaultCredentialMetaSchema = z.object({
+    key: z.string(),
+    label: z.string().optional(),
+    origins: z.array(z.string()).optional(),
+    originPatterns: z.array(z.string()).optional(),
+    hasTotp: z.boolean(),
+    source: VaultCredentialSourceSchema,
+    sourceDisplayName: z.string().optional(),
+});
+export const VaultListMetaOptionsSchema = z.object({
+    meta: z.literal(true),
+    prefix: z.string().optional(),
+    origin: z.string().optional(),
+    hasTotp: z.boolean().optional(),
+    limit: z.number().int().positive().optional(),
+});
+export const VaultListResultSchema = z.object({
+    keys: z.array(z.string()),
+});
+export const VaultListMetaResultSchema = z.object({
+    items: z.array(VaultCredentialMetaSchema),
+});

package/dist/contracts/version.d.ts

@@ -0,0 +1,3 @@
+export declare const PUBLIC_API_VERSION: "v1";
+export declare const PUBLIC_API_PREFIX: "/v1";
+export declare function withPublicApiPrefix(path: string): string;

package/dist/contracts/version.js

@@ -0,0 +1,16 @@
+export const PUBLIC_API_VERSION = 'v1';
+export const PUBLIC_API_PREFIX = `/${PUBLIC_API_VERSION}`;
+export function withPublicApiPrefix(path) {
+    if (typeof path !== 'string' || path.trim() === '') {
+        throw new Error('Public API path must be a non-empty string');
+    }
+    const normalizedPath = path.trim();
+    if (!normalizedPath.startsWith('/')) {
+        throw new Error(`Public API path must start with '/': ${normalizedPath}`);
+    }
+    if (normalizedPath === PUBLIC_API_PREFIX ||
+        normalizedPath.startsWith(`${PUBLIC_API_PREFIX}/`)) {
+        return normalizedPath;
+    }
+    return normalizedPath === '/' ? PUBLIC_API_PREFIX : `${PUBLIC_API_PREFIX}${normalizedPath}`;
+}

package/dist/desktop.d.ts

@@ -0,0 +1,2 @@
+export { default } from './drivers/desktop/index.js';
+export * from './drivers/desktop/index.js';

package/dist/desktop.js

@@ -0,0 +1,3 @@
+// Desktop driver entrypoint.
+export { default } from './drivers/desktop/index.js';
+export * from './drivers/desktop/index.js';

package/dist/drivers/desktop/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Desktop Driver - SDK for desktop automation
+ *
+ * Provides mouse, keyboard, screen, and window control via the desktop agent.
+ */
+import { DesktopSession } from './session.js';
+type InternalBctrlEnvironment = 'production' | 'development';
+export { DesktopSession, DesktopMouse, DesktopKeyboard, DesktopScreen, DesktopWindow, DesktopClipboard, DesktopCua, } from './session.js';
+export type { WindowInfo, Bounds, Point, Size, BrowserLaunchResult } from './session.js';
+export type { CuaAgentConfig, CuaRunOptions, CuaRunResult, CuaPredictClickResult, CuaAction, } from '../../contracts/desktop.js';
+export interface DesktopConnectOptions {
+    /** API key for authentication */
+    apiKey: string;
+    /**
+     * Target environment.
+     * Defaults to `production` (`https://api.bctrl.ai`).
+     * Use `development` for a local gateway on `http://localhost:8787`.
+     */
+    environment?: InternalBctrlEnvironment;
+    /**
+     * Gateway origin or API base URL.
+     * If you pass an origin, the SDK appends `/v1` automatically.
+     */
+    baseUrl?: string;
+}
+export declare const desktop: {
+    /**
+     * Connect to the desktop agent.
+     *
+     * @example
+     * ```ts
+     * import { desktop } from '@bctrl/sdk/desktop';
+     *
+     * const session = await desktop.connect({ apiKey: process.env.BCTRL_API_KEY! });
+     *
+     * // Mouse control
+     * await session.mouse.move(100, 200);
+     * await session.mouse.click();
+     *
+     * // Keyboard control
+     * await session.keyboard.type('Hello, World!');
+     * await session.keyboard.hotkey('Ctrl', 'C');
+     *
+     * // Screen capture
+     * const screenshot = await session.screen.capture();
+     *
+     * // Window management
+     * const windows = await session.window.list();
+     * await session.window.focus(windows[0].handle);
+     *
+     * // Launch browser for DOM control
+     * const browser = await session.launchBrowser();
+     * // Use browser.sessionId, browser.defaultContextId, browser.defaultPageId
+     *
+     * // CUA (Computer Use Agent) - AI-powered automation
+     * await session.cua.init();
+     * const result = await session.cua.run('Open Chrome and navigate to google.com');
+     * const { x, y } = await session.cua.predictClick('the search box');
+     * await session.mouse.move(x, y);
+     * await session.mouse.click();
+     * ```
+     */
+    connect(options: DesktopConnectOptions): Promise<DesktopSession>;
+};
+export default desktop;

package/dist/drivers/desktop/index.js

@@ -0,0 +1,68 @@
+/**
+ * Desktop Driver - SDK for desktop automation
+ *
+ * Provides mouse, keyboard, screen, and window control via the desktop agent.
+ */
+import { DesktopSession } from './session.js';
+import { fetchWithTimeout, parseJsonResponse, DEFAULT_TIMEOUT_MS } from '../../utils/http.js';
+import { BCTRL_DEVELOPMENT_ORIGIN, resolveApiKey, resolveInternalApiBaseUrl, } from '../../config.js';
+// Export session and namespace classes
+export { DesktopSession, DesktopMouse, DesktopKeyboard, DesktopScreen, DesktopWindow, DesktopClipboard, DesktopCua, } from './session.js';
+export const desktop = {
+    /**
+     * Connect to the desktop agent.
+     *
+     * @example
+     * ```ts
+     * import { desktop } from '@bctrl/sdk/desktop';
+     *
+     * const session = await desktop.connect({ apiKey: process.env.BCTRL_API_KEY! });
+     *
+     * // Mouse control
+     * await session.mouse.move(100, 200);
+     * await session.mouse.click();
+     *
+     * // Keyboard control
+     * await session.keyboard.type('Hello, World!');
+     * await session.keyboard.hotkey('Ctrl', 'C');
+     *
+     * // Screen capture
+     * const screenshot = await session.screen.capture();
+     *
+     * // Window management
+     * const windows = await session.window.list();
+     * await session.window.focus(windows[0].handle);
+     *
+     * // Launch browser for DOM control
+     * const browser = await session.launchBrowser();
+     * // Use browser.sessionId, browser.defaultContextId, browser.defaultPageId
+     *
+     * // CUA (Computer Use Agent) - AI-powered automation
+     * await session.cua.init();
+     * const result = await session.cua.run('Open Chrome and navigate to google.com');
+     * const { x, y } = await session.cua.predictClick('the search box');
+     * await session.mouse.move(x, y);
+     * await session.mouse.click();
+     * ```
+     */
+    async connect(options) {
+        const apiKey = resolveApiKey(options.apiKey);
+        const baseUrl = resolveInternalApiBaseUrl(options.baseUrl ?? (options.environment === 'development' ? BCTRL_DEVELOPMENT_ORIGIN : undefined));
+        const headers = {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+        };
+        const response = await fetchWithTimeout(`${baseUrl}/desktop/sessions`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({}),
+        }, DEFAULT_TIMEOUT_MS);
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Failed to create desktop session: ${text}`);
+        }
+        const data = await parseJsonResponse(response, 'Create desktop session');
+        return new DesktopSession(data.id, baseUrl, { apiKey });
+    },
+};
+export default desktop;

package/dist/drivers/desktop/session.d.ts

@@ -0,0 +1,313 @@
+/**
+ * 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 type { WindowInfo, Bounds, Point, Size, CuaAgentConfig, CuaRunOptions, CuaRunResult, CuaPredictClickResult, BrowserLaunchResult } from '../../contracts/desktop.js';
+export type { WindowInfo, Bounds, Point, Size, BrowserLaunchResult };
+export declare class DesktopSession {
+    readonly id: string;
+    readonly baseUrl: string;
+    private readonly apiKey?;
+    private _mouse;
+    private _keyboard;
+    private _screen;
+    private _window;
+    private _clipboard;
+    private _cua;
+    constructor(sessionId: string, baseUrl: string, options?: {
+        apiKey?: string;
+    });
+    /** Mouse control (move, click, drag, scroll) */
+    get mouse(): DesktopMouse;
+    /** Keyboard control (type, press, hotkey) */
+    get keyboard(): DesktopKeyboard;
+    /** Screen capture and display info */
+    get screen(): DesktopScreen;
+    /** Window management (list, focus, resize) */
+    get window(): DesktopWindow;
+    /** Clipboard read/write */
+    get clipboard(): DesktopClipboard;
+    /**
+     * CUA (Computer Use Agent) - AI-powered desktop automation.
+     * Similar to Stagehand for browser automation.
+     */
+    get cua(): DesktopCua;
+    /**
+     * 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
+     * ```
+     */
+    launchBrowser(options?: {
+        executablePath?: string;
+        headless?: boolean;
+        userDataDir?: string;
+        args?: string[];
+    }): Promise<BrowserLaunchResult>;
+    /**
+     * Close a launched browser.
+     */
+    closeBrowser(): Promise<void>;
+    /**
+     * Check if a browser is running.
+     */
+    isBrowserRunning(): Promise<boolean>;
+    /**
+     * Close the desktop session and clean up resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Send an RPC call to the desktop agent.
+     * @internal
+     */
+    rpc<T>(method: string, args: unknown[], target?: 'desktop' | 'cua'): Promise<T>;
+}
+/**
+ * Mouse control for desktop automation.
+ * Provides move, click, drag, and scroll operations.
+ */
+export declare class DesktopMouse {
+    private session;
+    constructor(session: DesktopSession);
+    /**
+     * 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)
+     */
+    move(x: number, y: number): Promise<void>;
+    /**
+     * Click at the current mouse position.
+     * @param button - Which mouse button to click (default: 'left')
+     */
+    click(button?: 'left' | 'right' | 'middle'): Promise<void>;
+    /**
+     * Double-click at the current mouse position.
+     */
+    doubleClick(): Promise<void>;
+    /**
+     * 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
+     */
+    drag(fromX: number, fromY: number, toX: number, toY: number): Promise<void>;
+    /**
+     * 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
+     */
+    scroll(deltaX: number, deltaY: number): Promise<void>;
+    /**
+     * Get the current mouse position.
+     * @returns Object with x and y coordinates in pixels
+     */
+    position(): Promise<Point>;
+}
+/**
+ * Keyboard control for desktop automation.
+ * Provides typing, key presses, and hotkey combinations.
+ */
+export declare class DesktopKeyboard {
+    private session;
+    constructor(session: DesktopSession);
+    /**
+     * Type a string of text.
+     * @param text - Text to type
+     */
+    type(text: string): Promise<void>;
+    /**
+     * Press a single key.
+     * @param key - Key to press (e.g., 'Enter', 'Tab', 'a')
+     */
+    press(key: string): Promise<void>;
+    /**
+     * Hold down a key.
+     * @param key - Key to hold down
+     */
+    down(key: string): Promise<void>;
+    /**
+     * Release a held key.
+     * @param key - Key to release
+     */
+    up(key: string): Promise<void>;
+    /**
+     * 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
+     * ```
+     */
+    hotkey(...keys: string[]): Promise<void>;
+}
+/**
+ * Screen control for desktop automation.
+ * Provides capture and display information.
+ */
+export declare class DesktopScreen {
+    private session;
+    constructor(session: DesktopSession);
+    /**
+     * Capture the screen or a region.
+     * @param region - Optional region to capture
+     * @returns PNG image as Buffer
+     */
+    capture(region?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): Promise<Buffer>;
+    /**
+     * Get the primary screen size.
+     * @returns Screen dimensions in pixels
+     */
+    size(): Promise<Size>;
+}
+/**
+ * Window management for desktop automation.
+ * Provides listing, focusing, and resizing windows.
+ */
+export declare class DesktopWindow {
+    private session;
+    constructor(session: DesktopSession);
+    /**
+     * List all visible windows.
+     * @returns Array of window information
+     */
+    list(): Promise<WindowInfo[]>;
+    /**
+     * Get the currently active (focused) window.
+     * @returns Active window info or null if none
+     */
+    active(): Promise<WindowInfo | null>;
+    /**
+     * Focus a window by handle.
+     * @param handle - Window handle from list()
+     */
+    focus(handle: number): Promise<void>;
+    /**
+     * Get window bounds.
+     * @param handle - Window handle
+     * @returns Window position and size
+     */
+    bounds(handle: number): Promise<Bounds>;
+    /**
+     * Set window bounds.
+     * @param handle - Window handle
+     * @param bounds - Partial bounds to set
+     */
+    setBounds(handle: number, bounds: Partial<Bounds>): Promise<void>;
+    /**
+     * Minimize a window.
+     * @param handle - Window handle
+     */
+    minimize(handle: number): Promise<void>;
+    /**
+     * Maximize a window.
+     * @param handle - Window handle
+     */
+    maximize(handle: number): Promise<void>;
+    /**
+     * Restore a minimized/maximized window.
+     * @param handle - Window handle
+     */
+    restore(handle: number): Promise<void>;
+    /**
+     * Close a window.
+     * @param handle - Window handle
+     */
+    close(handle: number): Promise<void>;
+}
+/**
+ * Clipboard operations for desktop automation.
+ */
+export declare class DesktopClipboard {
+    private session;
+    constructor(session: DesktopSession);
+    /**
+     * Read text from the clipboard.
+     * @returns Clipboard text content
+     */
+    read(): Promise<string>;
+    /**
+     * Write text to the clipboard.
+     * @param text - Text to write
+     */
+    write(text: string): Promise<void>;
+}
+/**
+ * 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 declare class DesktopCua {
+    private session;
+    constructor(session: DesktopSession);
+    /**
+     * 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' });
+     * ```
+     */
+    init(config?: CuaAgentConfig): Promise<{
+        success: boolean;
+        model: string;
+    }>;
+    /**
+     * Close the CUA agent and clean up resources.
+     */
+    close(): Promise<void>;
+    /**
+     * 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);
+     * ```
+     */
+    run(instruction: string, options?: CuaRunOptions): Promise<CuaRunResult>;
+    /**
+     * 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();
+     * ```
+     */
+    predictClick(instruction: string): Promise<CuaPredictClickResult>;
+}