@bctrl/sdk 1.0.1 → 1.0.2

package/dist/types.d.ts

@@ -0,0 +1,386 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export interface V2ListEnvelope<T> {
+    data: T[];
+    nextCursor: string | null;
+}
+export interface V2PageQuery {
+    cursor?: string;
+    limit?: number;
+}
+export interface V2SpaceCreateRequest {
+    name: string;
+    region: string;
+    subaccountId?: string | null;
+}
+export interface V2SpaceUpdateRequest {
+    name?: string;
+}
+export interface V2Space {
+    id: string;
+    name: string;
+    region: string;
+    subaccountId?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface V2SpaceEnvironment {
+    spaceId: string;
+    mounts: JsonObject;
+    updatedAt: string;
+}
+export interface V2SpaceEnvironmentUpdateRequest {
+    mounts: JsonObject;
+}
+export type V2RuntimeType = 'browser';
+export type V2RuntimeStatus = 'active' | 'stopped' | 'failed';
+export type V2BrowserStealth = 'medium' | 'high' | 'ultra';
+export type V2ProxyInput = {
+    mode: 'custom';
+    protocol: string;
+    host: string;
+    port: number;
+    username?: string;
+    password?: string;
+} | {
+    mode: 'saved';
+    id: string;
+    overrides?: JsonObject;
+};
+export interface V2RuntimeFingerprintCreateConfig {
+    browser?: string;
+    locale?: string;
+}
+export interface V2RuntimeLifecycleConfig {
+    idleTimeoutMinutes?: number;
+}
+export interface V2BrowserRuntimeCreateConfig {
+    browser?: {
+        profile?: boolean;
+    };
+    stealth?: V2BrowserStealth;
+    proxy?: V2ProxyInput | null;
+    fingerprint?: V2RuntimeFingerprintCreateConfig;
+    extensions?: string[];
+    lifecycle?: V2RuntimeLifecycleConfig;
+}
+export interface V2RuntimeCreateRequest {
+    spaceId: string;
+    type: V2RuntimeType;
+    name?: string;
+    metadata?: JsonObject;
+    config?: V2BrowserRuntimeCreateConfig;
+}
+export type V2SpaceRuntimeCreateRequest = Omit<V2RuntimeCreateRequest, 'spaceId'>;
+export interface V2RuntimeListQuery {
+    spaceId?: string;
+    status?: string | string[];
+    limit?: number;
+}
+export interface V2RuntimeSummary {
+    id: string;
+    name: string;
+    type: V2RuntimeType;
+    status: V2RuntimeStatus;
+    activeRunId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface V2Runtime extends V2RuntimeSummary {
+    config?: JsonObject;
+    metadata?: JsonObject | null;
+}
+export type V2ConnectionProtocol = 'cdp' | 'cua' | 'rdp' | 'vnc' | 'mcp' | 'http';
+export type V2ConnectionEndpoint = {
+    type: 'websocket';
+    url: string;
+} | {
+    type: 'http';
+    baseUrl: string;
+} | {
+    type: 'rdp';
+    host: string;
+    port: number;
+    username: string;
+    password: string;
+} | {
+    type: 'composite';
+    endpoints: Record<string, string>;
+};
+export interface V2RuntimeConnectionCreateRequest {
+    protocol: 'cdp';
+    options?: JsonObject;
+}
+export type V2RuntimeConnectionCreateOptions = Partial<V2RuntimeConnectionCreateRequest>;
+export interface V2RuntimeConnection {
+    id: string;
+    protocol: V2ConnectionProtocol;
+    status: string;
+    runId: string;
+    createdAt: string;
+    expiresAt: string | null;
+    closedAt?: string | null;
+    revokedAt?: string | null;
+}
+export interface V2RuntimeConnectionCreateResponse extends V2RuntimeConnection {
+    endpoint: V2ConnectionEndpoint;
+}
+export interface V2RuntimeStartResponse {
+    runtime: V2Runtime;
+    run: V2Run;
+}
+export interface V2RunListQuery extends V2PageQuery {
+    status?: string | string[];
+    spaceId?: string;
+    runtimeId?: string;
+}
+export type V2RuntimeRunListQuery = Omit<V2RunListQuery, 'spaceId' | 'runtimeId'>;
+export interface V2RunSummary {
+    id: string;
+    status: string;
+    createdAt: string;
+    startedAt: string;
+    finishedAt?: string | null;
+}
+export interface V2Run extends V2RunSummary {
+    spaceId: string;
+    runtimeId: string;
+    runtimeType: string;
+    durationMs?: number | null;
+    lastSeenAt?: string | null;
+    endedReason?: string | null;
+    failureReason?: string | null;
+}
+export interface V2RunEvent {
+    id: string;
+    runId: string;
+    runtimeId: string;
+    runtimeType: string;
+    type: string;
+    category: string;
+    time: string;
+    status?: string;
+    connectionId?: string;
+    commandId?: string;
+    invocationId?: string;
+    toolCallId?: string;
+    fileId?: string;
+    name?: string;
+    data?: JsonObject;
+}
+export interface V2RunEventsListQuery extends V2PageQuery {
+    type?: string | string[];
+    category?: string | string[];
+    connectionId?: string;
+}
+export interface V2RunEventsWaitRequest {
+    cursor?: string;
+    timeoutMs?: number;
+    type?: string[];
+    category?: string[];
+    connectionId?: string;
+}
+export interface V2RunEventsWaitResponse {
+    data: V2RunEvent | null;
+    cursor: string | null;
+    timedOut: boolean;
+}
+export type V2RunCommand = V2RunEvent & {
+    category: 'command';
+};
+export interface V2RunCommandsListQuery extends V2PageQuery {
+    type?: string | string[];
+    connectionId?: string;
+}
+export interface V2RunLiveRequest {
+    control?: string;
+    expiresInSeconds?: number;
+}
+export interface V2RunLiveResponse {
+    iframeUrl: string;
+    expiresAt: string;
+}
+export interface V2RunRecordingRequest {
+    expiresInSeconds?: number;
+}
+export interface V2RunRecordingResponse {
+    iframeUrl: string;
+    status: string;
+    durationMs?: number;
+    expiresAt: string;
+}
+export interface V2Invocation {
+    id: string;
+    runId: string;
+    spaceId: string;
+    runtimeId: string;
+    runtimeType: string;
+    type: string;
+    status: string;
+    result?: JsonValue | null;
+    error?: JsonObject | null;
+    progress?: JsonObject | null;
+    artifactCount: number;
+    createdAt: string;
+    startedAt?: string | null;
+    finishedAt?: string | null;
+    durationMs?: number | null;
+    metadata?: JsonObject | null;
+}
+export interface V2InvocationResponse {
+    data: V2Invocation;
+}
+export interface V2InvocationWaitRequest {
+    timeoutMs?: number;
+}
+export interface V2InvocationWaitResponse {
+    data: V2Invocation;
+    timedOut: boolean;
+}
+export type V2RuntimeInvocationFileInput = {
+    storagePath: string;
+    name?: string;
+} | {
+    fileId: string;
+    name?: string;
+};
+interface V2RuntimeInvocationAgentFields {
+    target?: JsonObject;
+    idempotencyKey?: string;
+    outputSchema?: JsonObject;
+    toolsetId?: string;
+    metadata?: JsonObject;
+    files?: V2RuntimeInvocationFileInput[];
+}
+export type V2RuntimeInvocationCreateRequest = {
+    provider: 'stagehand';
+    method: 'act' | 'observe';
+    target?: JsonObject;
+    input: JsonObject;
+    idempotencyKey?: string;
+    metadata?: JsonObject;
+} | {
+    provider: 'stagehand';
+    method: 'extract';
+    target?: JsonObject;
+    input?: JsonObject;
+    outputSchema?: JsonObject;
+    idempotencyKey?: string;
+    metadata?: JsonObject;
+} | (V2RuntimeInvocationAgentFields & {
+    provider: 'stagehand';
+    method: 'agent';
+    input: JsonObject;
+    config?: JsonObject;
+    options?: JsonObject;
+}) | (V2RuntimeInvocationAgentFields & {
+    provider: 'browserUse';
+    method: 'agent';
+    input: JsonObject;
+    config?: JsonObject;
+    options?: JsonObject;
+}) | {
+    provider: 'bctrl';
+    method: 'solveCaptcha';
+    target?: JsonObject;
+    input?: JsonObject;
+    idempotencyKey?: string;
+    metadata?: JsonObject;
+};
+export interface V2File {
+    id: string;
+    type: string;
+    source: 'upload' | 'runtime' | 'system';
+    name: string;
+    path: string;
+    contentType: string;
+    sizeBytes: number;
+    spaceId?: string;
+    runtimeId?: string | null;
+    runId?: string | null;
+    metadata?: JsonObject | null;
+    createdAt: string;
+    expiresAt?: string | null;
+    downloadUrl?: string;
+}
+export interface V2FilesListQuery extends V2PageQuery {
+    spaceId: string;
+    source?: 'upload' | 'runtime' | 'system';
+    path?: string;
+    prefix?: string;
+    query?: string;
+    contentType?: string;
+}
+export interface V2FileUpdateRequest {
+    name?: string;
+    metadata?: JsonObject | null;
+}
+export interface V2FileDeleteResponse {
+    success: true;
+}
+export interface V2FileUploadRequest {
+    spaceId: string;
+    file: Blob;
+    name?: string;
+    path?: string;
+    metadata?: JsonObject;
+}
+export interface V2RunFilesListQuery extends V2PageQuery {
+    type?: string | string[];
+}
+export interface V2RunFilesExportRequest {
+    format: 'zip';
+    name: string;
+    filter?: {
+        type?: string[];
+    };
+}
+export type V2RuntimeFileStageRequest = {
+    storagePath: string;
+    name?: string;
+} | {
+    fileId: string;
+    name?: string;
+};
+export interface V2RuntimeStagedFile {
+    id: string;
+    runtimeId: string;
+    runtimePath: string;
+    name: string;
+    sizeBytes: number;
+    expiresAt: string | null;
+}
+export interface V2RuntimeFileUploadRequest {
+    file: Blob;
+    name?: string;
+    storagePath?: string;
+    metadata?: JsonObject;
+}
+export interface V2RuntimeFileUploadResponse {
+    file: V2File;
+    staged: V2RuntimeStagedFile;
+}
+export interface V2RuntimeFileCollectRequest {
+    path: string;
+    storagePath?: string;
+    name?: string;
+    artifact?: {
+        kind?: string;
+        name?: string;
+        metadata?: JsonObject;
+    };
+}
+export interface BrowserLaunchOptions {
+    name: string;
+    state?: 'ephemeral' | 'profile';
+    metadata?: JsonObject;
+    lifecycle?: V2RuntimeLifecycleConfig;
+    stealth?: V2BrowserStealth;
+    proxy?: V2ProxyInput | null;
+    fingerprint?: V2RuntimeFingerprintCreateConfig;
+    extensions?: string[];
+}
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,4 @@
+export declare const BCTRL_PRODUCTION_ORIGIN = "https://api.bctrl.ai";
+export declare function stripTrailingSlash(value: string): string;
+export declare function resolveApiKey(apiKey: string): string;
+export declare function fetchWithTimeout(input: RequestInfo | URL, init?: RequestInit, timeoutMs?: number): Promise<Response>;

package/dist/utils.js

@@ -0,0 +1,27 @@
+export const BCTRL_PRODUCTION_ORIGIN = 'https://api.bctrl.ai';
+export function stripTrailingSlash(value) {
+    return value.replace(/\/+$/, '');
+}
+export function resolveApiKey(apiKey) {
+    const trimmed = apiKey.trim();
+    if (!trimmed) {
+        throw new Error('BCTRL_API_KEY is required. Pass apiKey or set BCTRL_API_KEY.');
+    }
+    return trimmed;
+}
+export async function fetchWithTimeout(input, init = {}, timeoutMs) {
+    if (!timeoutMs) {
+        return fetch(input, init);
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(input, {
+            ...init,
+            signal: init.signal ?? controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/version.js

@@ -1,4 +1,4 @@
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
-const pkg = require('../package.json');
-export const SDK_VERSION = pkg.version;
+const manifest = require('../package.json');
+export const SDK_VERSION = manifest.version ?? '0.0.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bctrl/sdk",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "BCTRL SDK - Remote browser automation",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -9,35 +9,11 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    },
-    "./puppeteer": {
-      "types": "./dist/puppeteer.d.ts",
-      "import": "./dist/puppeteer.js"
-    },
-    "./playwright": {
-      "types": "./dist/playwright.d.ts",
-      "import": "./dist/playwright.js"
-    },
-    "./stagehand": {
-      "types": "./dist/stagehand.d.ts",
-      "import": "./dist/stagehand.js"
-    },
-    "./selenium": {
-      "types": "./dist/selenium.d.ts",
-      "import": "./dist/selenium.js"
     }
   },
-  "scripts": {
-    "clean": "rm -rf dist",
-    "build": "pnpm run clean && tsc -p tsconfig.json",
-    "prepack": "pnpm run build",
-    "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit"
-  },
   "keywords": [],
   "author": "",
   "license": "ISC",
-  "packageManager": "pnpm@10.12.4",
   "devDependencies": {
     "@types/node": "^25.0.3",
     "@typescript-eslint/eslint-plugin": "^8.56.0",
@@ -46,11 +22,16 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
-  "dependencies": {
-    "@sentry/node": "^10.38.0",
-    "zod": "^4.2.1"
-  },
   "files": [
     "dist"
-  ]
-}
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "pnpm run clean && tsc -p tsconfig.json",
+    "dev": "tsc --watch",
+    "test": "tsx --test tests/v2/*.test.ts tests/v2/e2e/*.test.ts",
+    "test:v2": "tsx --test tests/v2/*.test.ts tests/v2/e2e/*.test.ts",
+    "test:v2:e2e": "BCTRL_E2E=1 tsx --test tests/v2/e2e/**/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/dist/agents/browser-use/index.d.ts

@@ -1 +0,0 @@
-export { BrowserUseNamespace } from './namespace.js';

package/dist/agents/browser-use/index.js

@@ -1,9 +0,0 @@
-// ============================================================================
-// Browser-use Agent - Autonomous browser automation
-// ============================================================================
-//
-// This module provides the browser-use agent integration for bctrl.
-// Browser-use agents can autonomously complete tasks using natural language.
-//
-// ============================================================================
-export { BrowserUseNamespace } from './namespace.js';

package/dist/agents/browser-use/namespace.d.ts

@@ -1,39 +0,0 @@
-import type { BrowserUseAgentConfig, BrowserUseCodeAgentConfig, BrowserUseAPI, BrowserUseAgent, BrowserUseCodeAgent } from '../../contracts/browser-use.js';
-import type { RpcSender } from '../../internal/transport.js';
-/**
- * Browser-use namespace - provides agent and codeAgent factory methods.
- */
-export declare class BrowserUseNamespace implements BrowserUseAPI {
-    private sendRpc;
-    private getActivePageId;
-    constructor(sendRpc: RpcSender, getActivePageId: () => string | undefined);
-    /**
-     * Create a reusable agent for natural language task execution.
-     * The agent can be used multiple times with different tasks.
-     *
-     * @example
-     * const agent = session.browserUse.agent({
-     *   llm: "gpt-4o",
-     *   useVision: true,
-     *   maxSteps: 20,
-     * });
-     *
-     * // Execute multiple tasks with the same agent
-     * const result1 = await agent.execute("Search for latest AI news");
-     * const result2 = await agent.execute("Find pricing information", { maxSteps: 10 });
-     */
-    agent(config?: BrowserUseAgentConfig): BrowserUseAgent;
-    /**
-     * Create a reusable code agent for code-based automation.
-     * Code agents generate and execute code to accomplish tasks.
-     *
-     * @example
-     * const codeAgent = session.browserUse.codeAgent({
-     *   llm: "gpt-4o",
-     * });
-     *
-     * // Execute tasks with the code agent
-     * const result = await codeAgent.execute("Fill out the registration form");
-     */
-    codeAgent(config?: BrowserUseCodeAgentConfig): BrowserUseCodeAgent;
-}

package/dist/agents/browser-use/namespace.js

@@ -1,93 +0,0 @@
-// ============================================================================
-// BrowserUseNamespace - Shared Browser-use agent methods for all drivers
-// ============================================================================
-//
-// This class provides the `.browserUse` namespace on driver sessions.
-// It creates Browser-use agents that can autonomously complete tasks.
-//
-// Usage (consistent with Stagehand agent pattern):
-//   const session = await bctrl.browser('my-scraper').connect.puppeteer();
-//
-//   // Create a reusable agent with configuration
-//   const agent = session.browserUse.agent({
-//     llm: "gpt-4o",
-//     useVision: true,
-//   });
-//
-//   // Execute tasks with the agent
-//   const result = await agent.execute("Search for AI news and summarize");
-//   const result2 = await agent.execute("Find pricing information", { maxSteps: 10 });
-//
-//   // Code agent works similarly
-//   const codeAgent = session.browserUse.codeAgent({ llm: "gpt-4o" });
-//   const codeResult = await codeAgent.execute("Fill out the form with test data");
-//
-// ============================================================================
-/**
- * Browser-use namespace - provides agent and codeAgent factory methods.
- */
-export class BrowserUseNamespace {
-    sendRpc;
-    getActivePageId;
-    constructor(sendRpc, getActivePageId) {
-        this.sendRpc = sendRpc;
-        this.getActivePageId = getActivePageId;
-    }
-    /**
-     * Create a reusable agent for natural language task execution.
-     * The agent can be used multiple times with different tasks.
-     *
-     * @example
-     * const agent = session.browserUse.agent({
-     *   llm: "gpt-4o",
-     *   useVision: true,
-     *   maxSteps: 20,
-     * });
-     *
-     * // Execute multiple tasks with the same agent
-     * const result1 = await agent.execute("Search for latest AI news");
-     * const result2 = await agent.execute("Find pricing information", { maxSteps: 10 });
-     */
-    agent(config) {
-        const agentConfig = config || {};
-        const pageId = agentConfig.pageId || this.getActivePageId();
-        const rpc = this.sendRpc;
-        return {
-            execute: async (task, options) => {
-                const executeOptions = {
-                    task,
-                    ...(options?.maxSteps !== undefined ? { maxSteps: options.maxSteps } : {}),
-                    ...(options?.tools !== undefined ? { tools: options.tools } : {}),
-                };
-                return rpc('browserUse', 'agent.execute', [agentConfig, executeOptions], { pageId });
-            },
-        };
-    }
-    /**
-     * Create a reusable code agent for code-based automation.
-     * Code agents generate and execute code to accomplish tasks.
-     *
-     * @example
-     * const codeAgent = session.browserUse.codeAgent({
-     *   llm: "gpt-4o",
-     * });
-     *
-     * // Execute tasks with the code agent
-     * const result = await codeAgent.execute("Fill out the registration form");
-     */
-    codeAgent(config) {
-        const agentConfig = config || {};
-        const pageId = agentConfig.pageId || this.getActivePageId();
-        const rpc = this.sendRpc;
-        return {
-            execute: async (task, options) => {
-                const executeOptions = {
-                    task,
-                    ...(options?.maxSteps !== undefined ? { maxSteps: options.maxSteps } : {}),
-                    ...(options?.tools !== undefined ? { tools: options.tools } : {}),
-                };
-                return rpc('browserUse', 'codeAgent.execute', [agentConfig, executeOptions], { pageId });
-            },
-        };
-    }
-}

package/dist/agents/index.d.ts

@@ -1,2 +0,0 @@
-export { StagehandNamespace, StagehandAgent } from './stagehand/index.js';
-export { BrowserUseNamespace } from './browser-use/index.js';

package/dist/agents/index.js

@@ -1,17 +0,0 @@
-// ============================================================================
-// AI Agents - Unified AI-powered browser automation
-// ============================================================================
-//
-// This module provides all AI agent integrations for bctrl:
-//
-// - Stagehand: AI-powered browser automation with act, extract, observe
-// - Browser-use: Autonomous agents for natural language task execution
-//
-// These agents work across all drivers (Puppeteer, Playwright, Selenium, Stagehand)
-// through the `.stagehand` and `.browserUse` namespaces on sessions.
-//
-// ============================================================================
-// Stagehand AI exports
-export { StagehandNamespace, StagehandAgent } from './stagehand/index.js';
-// Browser-use exports
-export { BrowserUseNamespace } from './browser-use/index.js';