@bctrl/sdk 1.0.1

package/dist/drivers/stagehand/generated/response.js

@@ -0,0 +1,232 @@
+/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * Generated from: packages/automation-spec/src/drivers/stagehand/methods/
+ * Run `pnpm generate:stagehand` to regenerate.
+ */
+/**
+ * RemoteStagehandResponse - Remote Puppeteer Response API over RPC.
+ *
+ * @see https://pptr.dev/api/puppeteer.response
+ */
+export class RemoteStagehandResponse {
+    sendRpc;
+    _id;
+    _url;
+    _status;
+    _statusText;
+    _ok;
+    _headers;
+    _fromServiceWorker;
+    constructor(sendRpc, data) {
+        this.sendRpc = sendRpc;
+        this._id = data.id;
+        this._url = data.url;
+        this._status = data.status;
+        this._statusText = data.statusText;
+        this._ok = data.ok;
+        this._headers = data.headers;
+        this._fromServiceWorker = data.fromServiceWorker;
+    }
+    rpc(method, args) {
+        return this.sendRpc(method, args);
+    }
+    /**
+     * Get the frame that initiated this response (synchronous version).
+     * Note: Not fully supported in remote SDK.
+     */
+    frame() {
+        return null;
+    }
+    /**
+     * Get the URL of the response.
+     *
+     * @example
+     * const url = response.url();
+     *
+     * @see https://docs.stagehand.dev/references/response#url
+     */
+    url() {
+        return this._url;
+    }
+    /**
+     * Get the HTTP status code of the response.
+     *
+     * @example
+     * const statusCode = response.status();
+     *
+     * @see https://docs.stagehand.dev/references/response#status
+     */
+    status() {
+        return this._status;
+    }
+    /**
+     * Get the HTTP status text of the response.
+     *
+     * @example
+     * const text = response.statusText();
+     *
+     * @see https://docs.stagehand.dev/references/response#statustext
+     */
+    statusText() {
+        return this._statusText;
+    }
+    /**
+     * Check if the response status is in the 200-299 range.
+     *
+     * @example
+     * if (response.ok()) { console.log("success"); }
+     *
+     * @see https://docs.stagehand.dev/references/response#ok
+     */
+    ok() {
+        return this._ok;
+    }
+    /**
+     * Check if the response was served from a service worker.
+     *
+     * @example
+     * const fromSW = response.fromServiceWorker();
+     *
+     * @see https://docs.stagehand.dev/references/response#fromserviceworker
+     */
+    fromServiceWorker() {
+        return this._fromServiceWorker;
+    }
+    /**
+     * Get the security details of the response (for HTTPS).
+     *
+     * @remarks
+     * Returns null for non-HTTPS responses.
+     *
+     * @example
+     * const security = await response.securityDetails();
+     *
+     * @see https://docs.stagehand.dev/references/response#securitydetails
+     */
+    async securityDetails() {
+        return this.rpc('securityDetails', []);
+    }
+    /**
+     * Get the server address (IP and port) that served the response.
+     *
+     * @example
+     * const addr = await response.serverAddr();
+     *
+     * @see https://docs.stagehand.dev/references/response#serveraddr
+     */
+    async serverAddr() {
+        return this.rpc('serverAddr', []);
+    }
+    /**
+     * Get all response headers as an object.
+     *
+     * @remarks
+     * Header names are lower-cased. Multiple values for the same header are joined with ", ".
+     *
+     * @example
+     * const headers = response.headers();
+     *
+     * @see https://docs.stagehand.dev/references/response#headers
+     */
+    headers() {
+        return this._headers;
+    }
+    /**
+     * Get all response headers including those not exposed by the standard API.
+     *
+     * @example
+     * const allHeaders = await response.allHeaders();
+     *
+     * @see https://docs.stagehand.dev/references/response#allheaders
+     */
+    async allHeaders() {
+        return this.rpc('allHeaders', []);
+    }
+    /**
+     * Get the value of a specific header.
+     * @param name - Header name (case-insensitive).
+     *
+     * @example
+     * const contentType = await response.headerValue("content-type");
+     *
+     * @see https://docs.stagehand.dev/references/response#headervalue
+     */
+    async headerValue(name) {
+        return this.rpc('headerValue', [name]);
+    }
+    /**
+     * Get all values of a specific header (for headers with multiple values).
+     * @param name - Header name (case-insensitive).
+     *
+     * @example
+     * const cookies = await response.headerValues("set-cookie");
+     *
+     * @see https://docs.stagehand.dev/references/response#headervalues
+     */
+    async headerValues(name) {
+        return this.rpc('headerValues', [name]);
+    }
+    /**
+     * Get all response headers as an array of { name, value } objects.
+     *
+     * @remarks
+     * Preserves multiple values for the same header as separate entries.
+     *
+     * @example
+     * const headersArray = await response.headersArray();
+     *
+     * @see https://docs.stagehand.dev/references/response#headersarray
+     */
+    async headersArray() {
+        return this.rpc('headersArray', []);
+    }
+    /**
+     * Get the response body as a Buffer.
+     *
+     * @example
+     * const buffer = await response.body();
+     *
+     * @see https://docs.stagehand.dev/references/response#body
+     */
+    async body() {
+        const result = await this.rpc('body', []);
+        return Buffer.from(result, 'base64');
+    }
+    /**
+     * Get the response body as text.
+     *
+     * @example
+     * const text = await response.text();
+     *
+     * @see https://docs.stagehand.dev/references/response#text
+     */
+    async text() {
+        return this.rpc('text', []);
+    }
+    /**
+     * Get the response body parsed as JSON.
+     *
+     * @example
+     * const data = await response.json();
+     *
+     * @see https://docs.stagehand.dev/references/response#json
+     */
+    async json() {
+        return this.rpc('json', []);
+    }
+    /**
+     * Wait for the response to finish and get any error message.
+     *
+     * @remarks
+     * Returns null if the response was successful, or an error message if it failed.
+     *
+     * @example
+     * const error = await response.finished();
+     *
+     * @see https://docs.stagehand.dev/references/response#finished
+     */
+    async finished() {
+        return this.rpc('finished', []);
+    }
+}

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

@@ -0,0 +1,5 @@
+export * from './types.js';
+export { RemoteStagehandPage } from './generated/page.js';
+export { RemoteStagehandLocator } from './generated/locator.js';
+export { RemoteStagehandContext } from './generated/context.js';
+export { RemoteStagehandResponse } from './generated/response.js';

package/dist/drivers/stagehand/index.js

@@ -0,0 +1,8 @@
+// Stagehand driver exports.
+// Re-export types
+export * from './types.js';
+// Generated classes
+export { RemoteStagehandPage } from './generated/page.js';
+export { RemoteStagehandLocator } from './generated/locator.js';
+export { RemoteStagehandContext } from './generated/context.js';
+export { RemoteStagehandResponse } from './generated/response.js';

package/dist/drivers/stagehand/types.d.ts

@@ -0,0 +1 @@
+export type { StagehandLoadState, StagehandGotoOptions, StagehandReloadOptions, StagehandClickOptions, StagehandHoverOptions, StagehandDragAndDropOptions, StagehandTypeOptions, StagehandLocatorClickOptions, StagehandLocatorTypeOptions, StagehandHighlightOptions, StagehandSendClickEventOptions, StagehandFilePayload, StagehandFileInput, StagehandWaitForSelectorOptions, StagehandScreenshotClip, StagehandScreenshotOptions, StagehandSnapshotOptions, StagehandSnapshotResult, StagehandViewportSize, StagehandViewportOptions, StagehandSecurityDetails, StagehandServerAddr, StagehandHeaderEntry, StagehandInitScriptSource, } from '../../contracts/drivers/stagehand.js';

package/dist/drivers/stagehand/types.js

@@ -0,0 +1,7 @@
+// ============================================================================
+// Stagehand Driver Types
+// ============================================================================
+//
+// Re-export type definitions from the SDK-local Stagehand contract module.
+// ============================================================================
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,47 @@
+import { type AutomationDiagnostic } from './contracts/automation.js';
+/**
+ * Base error class for all bctrl SDK errors.
+ * Carries a fine-grained `.code` and optional `.context` metadata.
+ */
+export declare class BctrlError extends Error {
+    readonly code: string;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, context?: Record<string, unknown> | undefined);
+    /** Serialize for structured loggers (pino, winston) and JSON.stringify() */
+    toJSON(): Record<string, unknown>;
+}
+/** Automation/driver/script errors — your code or selectors need fixing */
+export declare class AutomationError extends BctrlError {
+    constructor(message: string, code?: string, context?: Record<string, unknown>);
+    /** Human-readable suggestion from control-plane validation. */
+    get hint(): string | undefined;
+    /** Structured diagnostic payload with machine-readable fix metadata. */
+    get diagnostic(): AutomationDiagnostic | undefined;
+}
+/** Session/browser lifecycle errors — reconnect or recreate */
+export declare class SessionError extends BctrlError {
+    constructor(message: string, code?: string, context?: Record<string, unknown>);
+}
+/** Timeout errors — increase timeout or retry */
+export declare class TimeoutError extends BctrlError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/** Authentication/authorization errors — check API key */
+export declare class AuthenticationError extends BctrlError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/** Reconstruct a typed error from the wire format (errorCode + errorContext) */
+export declare function fromErrorResponse(message: string, code?: string, context?: Record<string, unknown>): BctrlError;
+export declare function isBctrlError(error: unknown): error is BctrlError;
+export declare function isAutomationError(error: unknown): error is AutomationError;
+export declare function isSessionError(error: unknown): error is SessionError;
+export declare function isTimeoutError(error: unknown): error is TimeoutError;
+export declare function isAuthenticationError(error: unknown): error is AuthenticationError;
+/**
+ * Get a typed automation hint from an SDK error when available.
+ */
+export declare function getAutomationHint(error: unknown): string | undefined;
+/**
+ * Get a typed automation diagnostic payload from an SDK error when available.
+ */
+export declare function getAutomationDiagnostic(error: unknown): AutomationDiagnostic | undefined;

package/dist/errors.js

@@ -0,0 +1,157 @@
+// ============================================================================
+// SDK Error Hierarchy
+// ============================================================================
+//
+// User-facing error classes oriented around what action to take:
+// - AutomationError  → fix selectors, script code, or arguments
+// - SessionError     → recreate session, check if browser/host is up
+// - TimeoutError     → increase timeout or retry
+// - AuthenticationError → check/refresh API key
+// ============================================================================
+import { AutomationDiagnosticSchema } from './contracts/automation.js';
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function isAutomationDiagnostic(value) {
+    return AutomationDiagnosticSchema.safeParse(value).success;
+}
+function getContextHint(context) {
+    if (!context)
+        return undefined;
+    const hint = context.hint;
+    return typeof hint === 'string' && hint.length > 0 ? hint : undefined;
+}
+function getContextDiagnostic(context) {
+    if (!context)
+        return undefined;
+    const diagnostic = context.diagnostic;
+    return isAutomationDiagnostic(diagnostic) ? diagnostic : undefined;
+}
+/**
+ * Base error class for all bctrl SDK errors.
+ * Carries a fine-grained `.code` and optional `.context` metadata.
+ */
+export class BctrlError extends Error {
+    code;
+    context;
+    constructor(message, code, context) {
+        super(message);
+        this.code = code;
+        this.context = context;
+        this.name = 'BctrlError';
+        if (Error.captureStackTrace)
+            Error.captureStackTrace(this, this.constructor);
+    }
+    /** Serialize for structured loggers (pino, winston) and JSON.stringify() */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            context: this.context,
+            stack: this.stack,
+        };
+    }
+}
+/** Automation/driver/script errors — your code or selectors need fixing */
+export class AutomationError extends BctrlError {
+    constructor(message, code = 'DRIVER_ERROR', context) {
+        super(message, code, context);
+        this.name = 'AutomationError';
+    }
+    /** Human-readable suggestion from control-plane validation. */
+    get hint() {
+        return getContextHint(this.context);
+    }
+    /** Structured diagnostic payload with machine-readable fix metadata. */
+    get diagnostic() {
+        return getContextDiagnostic(this.context);
+    }
+}
+/** Session/browser lifecycle errors — reconnect or recreate */
+export class SessionError extends BctrlError {
+    constructor(message, code = 'SESSION_ERROR', context) {
+        super(message, code, context);
+        this.name = 'SessionError';
+    }
+}
+/** Timeout errors — increase timeout or retry */
+export class TimeoutError extends BctrlError {
+    constructor(message, context) {
+        super(message, 'TIMEOUT_ERROR', context);
+        this.name = 'TimeoutError';
+    }
+}
+/** Authentication/authorization errors — check API key */
+export class AuthenticationError extends BctrlError {
+    constructor(message, context) {
+        super(message, 'AUTH_ERROR', context);
+        this.name = 'AuthenticationError';
+    }
+}
+// ============================================================================
+// Wire Format Reconstruction
+// ============================================================================
+/** Reconstruct a typed error from the wire format (errorCode + errorContext) */
+export function fromErrorResponse(message, code, context) {
+    switch (code) {
+        case 'DRIVER_ERROR':
+        case 'EXECUTION_ERROR':
+        case 'VALIDATION_ERROR':
+            return new AutomationError(message, code, context);
+        case 'SESSION_ERROR':
+        case 'NOT_FOUND':
+        case 'SESSION_NOT_FOUND':
+        case 'DRIVER_NOT_CONNECTED':
+        case 'CONNECTION_ERROR':
+        case 'RPC_ERROR':
+            return new SessionError(message, code, context);
+        case 'TIMEOUT_ERROR':
+        case 'TIMEOUT':
+            return new TimeoutError(message, context);
+        case 'AUTH_ERROR':
+            return new AuthenticationError(message, context);
+        default:
+            return new BctrlError(message, code || 'UNKNOWN_ERROR', context);
+    }
+}
+// ============================================================================
+// Type Guards
+// ============================================================================
+//
+// These use structural checks as a fallback for environments where
+// instanceof fails (bundler duplication, multiple package copies in monorepos).
+export function isBctrlError(error) {
+    return error instanceof BctrlError || (error instanceof Error && 'code' in error && typeof error.code === 'string'
+        && (error.name === 'BctrlError' || error.name === 'AutomationError'
+            || error.name === 'SessionError' || error.name === 'TimeoutError'
+            || error.name === 'AuthenticationError'));
+}
+export function isAutomationError(error) {
+    return error instanceof AutomationError || (isBctrlError(error) && error.name === 'AutomationError');
+}
+export function isSessionError(error) {
+    return error instanceof SessionError || (isBctrlError(error) && error.name === 'SessionError');
+}
+export function isTimeoutError(error) {
+    return error instanceof TimeoutError || (isBctrlError(error) && error.name === 'TimeoutError');
+}
+export function isAuthenticationError(error) {
+    return error instanceof AuthenticationError || (isBctrlError(error) && error.name === 'AuthenticationError');
+}
+/**
+ * Get a typed automation hint from an SDK error when available.
+ */
+export function getAutomationHint(error) {
+    if (!isBctrlError(error))
+        return undefined;
+    return getContextHint(error.context);
+}
+/**
+ * Get a typed automation diagnostic payload from an SDK error when available.
+ */
+export function getAutomationDiagnostic(error) {
+    if (!isBctrlError(error))
+        return undefined;
+    return getContextDiagnostic(error.context);
+}

package/dist/extensions/client.d.ts

@@ -0,0 +1,47 @@
+import type { ExtensionMetadata } from '../contracts/extensions.js';
+export declare class ExtensionsClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    constructor(baseUrl: string, apiKey?: string | undefined);
+    private headers;
+    private jsonHeaders;
+    /**
+     * Upload an extension from a file buffer or Chrome Web Store URL.
+     */
+    upload(opts: {
+        file?: Buffer;
+        filename?: string;
+        url?: string;
+    }): Promise<ExtensionMetadata>;
+    /**
+     * List all uploaded extensions.
+     */
+    list(): Promise<ExtensionMetadata[]>;
+    /**
+     * Get extension metadata by ID.
+     */
+    get(id: string): Promise<ExtensionMetadata | null>;
+    /**
+     * Update an existing extension with a new file.
+     */
+    update(id: string, opts: {
+        file: Buffer;
+        filename: string;
+    }): Promise<ExtensionMetadata>;
+    /**
+     * Delete an extension.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Install extension(s) on a browser profile.
+     */
+    install(browserName: string, extensionIds: string | string[]): Promise<void>;
+    /**
+     * Uninstall an extension from a browser profile.
+     */
+    uninstall(browserName: string, extensionId: string): Promise<void>;
+    /**
+     * List extensions installed on a browser profile.
+     */
+    installed(browserName: string): Promise<ExtensionMetadata[]>;
+}

package/dist/extensions/client.js

@@ -0,0 +1,154 @@
+/**
+ * ExtensionsClient — SDK client for browser extension management.
+ *
+ * Handles account-level extension CRUD and profile-level install/uninstall.
+ */
+import { fetchWithTimeout, parseJsonResponse } from '../utils/http.js';
+import { SDK_VERSION } from '../version.js';
+// ============================================================================
+// ExtensionsClient
+// ============================================================================
+export class ExtensionsClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+    }
+    headers() {
+        const h = {
+            'x-sdk-version': SDK_VERSION,
+        };
+        if (this.apiKey)
+            h['Authorization'] = `Bearer ${this.apiKey}`;
+        return h;
+    }
+    jsonHeaders() {
+        return { 'Content-Type': 'application/json', ...this.headers() };
+    }
+    // --------------------------------------------------------------------------
+    // Account-level extension management
+    // --------------------------------------------------------------------------
+    /**
+     * Upload an extension from a file buffer or Chrome Web Store URL.
+     */
+    async upload(opts) {
+        if (opts.url) {
+            // JSON body with URL
+            const res = await fetchWithTimeout(`${this.baseUrl}/extensions/upload`, {
+                method: 'POST',
+                headers: this.jsonHeaders(),
+                body: JSON.stringify({ url: opts.url }),
+            });
+            if (!res.ok)
+                throw new Error(`Extension upload failed: ${await res.text()}`);
+            return parseJsonResponse(res, 'Extension upload');
+        }
+        if (!opts.file) {
+            throw new Error('Either file or url must be provided');
+        }
+        // Multipart file upload
+        const formData = new FormData();
+        const blob = new Blob([new Uint8Array(opts.file)], { type: 'application/octet-stream' });
+        formData.append('file', blob, opts.filename || 'extension.crx');
+        const res = await fetchWithTimeout(`${this.baseUrl}/extensions/upload`, {
+            method: 'POST',
+            headers: this.headers(), // No Content-Type — FormData sets it with boundary
+            body: formData,
+        });
+        if (!res.ok)
+            throw new Error(`Extension upload failed: ${await res.text()}`);
+        return parseJsonResponse(res, 'Extension upload');
+    }
+    /**
+     * List all uploaded extensions.
+     */
+    async list() {
+        const res = await fetchWithTimeout(`${this.baseUrl}/extensions`, {
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw new Error(`Extension list failed: ${await res.text()}`);
+        const data = await parseJsonResponse(res, 'Extension list');
+        return data.extensions;
+    }
+    /**
+     * Get extension metadata by ID.
+     */
+    async get(id) {
+        const res = await fetchWithTimeout(`${this.baseUrl}/extensions/${encodeURIComponent(id)}`, {
+            headers: this.headers(),
+        });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`Extension get failed: ${await res.text()}`);
+        return parseJsonResponse(res, 'Extension get');
+    }
+    /**
+     * Update an existing extension with a new file.
+     */
+    async update(id, opts) {
+        const formData = new FormData();
+        const blob = new Blob([new Uint8Array(opts.file)], { type: 'application/octet-stream' });
+        formData.append('file', blob, opts.filename);
+        const res = await fetchWithTimeout(`${this.baseUrl}/extensions/${encodeURIComponent(id)}`, {
+            method: 'PUT',
+            headers: this.headers(),
+            body: formData,
+        });
+        if (!res.ok)
+            throw new Error(`Extension update failed: ${await res.text()}`);
+        return parseJsonResponse(res, 'Extension update');
+    }
+    /**
+     * Delete an extension.
+     */
+    async delete(id) {
+        const res = await fetchWithTimeout(`${this.baseUrl}/extensions/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw new Error(`Extension delete failed: ${await res.text()}`);
+    }
+    // --------------------------------------------------------------------------
+    // Profile-level install/uninstall
+    // --------------------------------------------------------------------------
+    /**
+     * Install extension(s) on a browser profile.
+     */
+    async install(browserName, extensionIds) {
+        const ids = Array.isArray(extensionIds) ? extensionIds : [extensionIds];
+        const res = await fetchWithTimeout(`${this.baseUrl}/profiles/by-name/${encodeURIComponent(browserName)}/extensions`, {
+            method: 'POST',
+            headers: this.jsonHeaders(),
+            body: JSON.stringify({ extensionIds: ids }),
+        });
+        if (!res.ok)
+            throw new Error(`Extension install failed: ${await res.text()}`);
+    }
+    /**
+     * Uninstall an extension from a browser profile.
+     */
+    async uninstall(browserName, extensionId) {
+        const res = await fetchWithTimeout(`${this.baseUrl}/profiles/by-name/${encodeURIComponent(browserName)}/extensions/${encodeURIComponent(extensionId)}`, {
+            method: 'DELETE',
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw new Error(`Extension uninstall failed: ${await res.text()}`);
+    }
+    /**
+     * List extensions installed on a browser profile.
+     */
+    async installed(browserName) {
+        const res = await fetchWithTimeout(`${this.baseUrl}/profiles/by-name/${encodeURIComponent(browserName)}/extensions`, {
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw new Error(`Extension installed list failed: ${await res.text()}`);
+        const data = await parseJsonResponse(res, 'Extension installed list');
+        return data.extensions;
+    }
+}

package/dist/extensions/index.d.ts

@@ -0,0 +1 @@
+export { ExtensionsClient } from './client.js';

package/dist/extensions/index.js

@@ -0,0 +1 @@
+export { ExtensionsClient } from './client.js';

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { z } from 'zod';
+export type { ZodType } from 'zod';
+export { BctrlError, AutomationError, AutomationError as SdkAutomationError, SessionError, TimeoutError, AuthenticationError, fromErrorResponse, isBctrlError, isAutomationError, isSessionError, isTimeoutError, isAuthenticationError, getAutomationHint, } from './errors.js';
+export * from './storage/index.js';
+export * from './ai-credentials/index.js';
+export * from './browser-extensions/index.js';
+export * from './browser-profiles/index.js';
+export * from './vault/index.js';
+export * from './updates/index.js';
+export * from './workspaces/index.js';
+export type { BctrlOptions } from './bctrl.js';
+export { Bctrl } from './bctrl.js';