@bctrl/sdk 1.0.1 → 1.0.3

package/dist/types.d.ts

@@ -0,0 +1,413 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export interface V1ListEnvelope<T> {
+    data: T[];
+    nextCursor: string | null;
+}
+export interface V1PageQuery {
+    cursor?: string;
+    limit?: number;
+}
+export interface V1SpaceCreateRequest {
+    name: string;
+    region: string;
+    subaccountId?: string | null;
+}
+export interface V1SpaceUpdateRequest {
+    name?: string;
+}
+export interface V1Space {
+    id: string;
+    name: string;
+    region: string;
+    subaccountId?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface V1SpaceEnvironment {
+    spaceId: string;
+    mounts: JsonObject;
+    updatedAt: string;
+}
+export interface V1SpaceEnvironmentUpdateRequest {
+    mounts: JsonObject;
+}
+export type V1RuntimeType = 'browser';
+export type V1RuntimeStatus = 'active' | 'stopped' | 'failed';
+export type V1BrowserStealth = 'medium' | 'high' | 'ultra';
+export type V1ProxyInput = {
+    mode: 'custom';
+    protocol: string;
+    host: string;
+    port: number;
+    username?: string;
+    password?: string;
+} | {
+    mode: 'saved';
+    id: string;
+    overrides?: JsonObject;
+};
+export interface V1RuntimeFingerprintCreateConfig {
+    browser?: string;
+    locale?: string;
+}
+export interface V1RuntimeLifecycleConfig {
+    idleTimeoutMinutes?: number;
+}
+export interface V1BrowserRuntimeCreateConfig {
+    browser?: {
+        profile?: boolean;
+    };
+    stealth?: V1BrowserStealth;
+    proxy?: V1ProxyInput | null;
+    fingerprint?: V1RuntimeFingerprintCreateConfig;
+    extensions?: string[];
+    lifecycle?: V1RuntimeLifecycleConfig;
+}
+export interface V1RuntimeCreateRequest {
+    spaceId: string;
+    type: V1RuntimeType;
+    name?: string;
+    metadata?: JsonObject;
+    config?: V1BrowserRuntimeCreateConfig;
+}
+export type V1SpaceRuntimeCreateRequest = Omit<V1RuntimeCreateRequest, 'spaceId'>;
+export interface V1RuntimeListQuery {
+    spaceId?: string;
+    status?: string | string[];
+    limit?: number;
+}
+export interface V1RuntimeSummary {
+    id: string;
+    name: string;
+    type: V1RuntimeType;
+    status: V1RuntimeStatus;
+    activeRunId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface V1Runtime extends V1RuntimeSummary {
+    config?: JsonObject;
+    metadata?: JsonObject | null;
+}
+export type V1ConnectionProtocol = 'cdp' | 'cua' | 'rdp' | 'vnc' | 'mcp' | 'http';
+export type V1ConnectionEndpoint = {
+    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 V1RuntimeConnectionCreateRequest {
+    protocol: 'cdp';
+    options?: JsonObject;
+}
+export type V1RuntimeConnectionCreateOptions = Partial<V1RuntimeConnectionCreateRequest>;
+export interface V1RuntimeConnection {
+    id: string;
+    protocol: V1ConnectionProtocol;
+    status: string;
+    runId: string;
+    createdAt: string;
+    expiresAt: string | null;
+    closedAt?: string | null;
+    revokedAt?: string | null;
+}
+export interface V1RuntimeConnectionCreateResponse extends V1RuntimeConnection {
+    endpoint: V1ConnectionEndpoint;
+}
+export interface V1RuntimeStartResponse {
+    runtime: V1Runtime;
+    run: V1Run;
+}
+export interface V1RunListQuery extends V1PageQuery {
+    status?: string | string[];
+    spaceId?: string;
+    runtimeId?: string;
+}
+export type V1RuntimeRunListQuery = Omit<V1RunListQuery, 'spaceId' | 'runtimeId'>;
+export interface V1RunSummary {
+    id: string;
+    status: string;
+    createdAt: string;
+    startedAt: string;
+    finishedAt?: string | null;
+}
+export interface V1Run extends V1RunSummary {
+    spaceId: string;
+    runtimeId: string;
+    runtimeType: string;
+    durationMs?: number | null;
+    lastSeenAt?: string | null;
+    endedReason?: string | null;
+    failureReason?: string | null;
+}
+export interface V1RunUsage {
+    runId: string;
+    runtimeId: string;
+    runtimeType: string;
+    status: string;
+    computedAt: string;
+    usage: {
+        runtime: {
+            seconds: number | null;
+            billingClass: string | null;
+        };
+        aiTokens: {
+            input: number | null;
+            output: number | null;
+            total: number | null;
+        };
+        proxyBytes: number | null;
+        captchaSolves: number;
+        files: {
+            count: number;
+            bytes: number;
+        };
+        invocations: number;
+        toolCalls: number;
+    };
+    billing: {
+        status: 'pending' | 'settled' | 'unavailable';
+        creditCost: number | null;
+        breakdown: {
+            runtime: number | null;
+            ai: number | null;
+            proxy: number | null;
+            captcha: number | null;
+            files: number | null;
+        };
+    };
+}
+export interface V1RunEvent {
+    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 V1RunEventsListQuery extends V1PageQuery {
+    type?: string | string[];
+    category?: string | string[];
+    connectionId?: string;
+}
+export interface V1RunEventsWaitRequest {
+    cursor?: string;
+    timeoutMs?: number;
+    type?: string[];
+    category?: string[];
+    connectionId?: string;
+}
+export interface V1RunEventsWaitResponse {
+    data: V1RunEvent | null;
+    cursor: string | null;
+    timedOut: boolean;
+}
+export type V1RunCommand = V1RunEvent & {
+    category: 'command';
+};
+export interface V1RunCommandsListQuery extends V1PageQuery {
+    type?: string | string[];
+    connectionId?: string;
+}
+export interface V1RunLiveRequest {
+    control?: string;
+    expiresInSeconds?: number;
+}
+export interface V1RunLiveResponse {
+    iframeUrl: string;
+    expiresAt: string;
+}
+export interface V1RunRecordingRequest {
+    expiresInSeconds?: number;
+}
+export interface V1RunRecordingResponse {
+    iframeUrl: string;
+    status: string;
+    durationMs?: number;
+    expiresAt: string;
+}
+export interface V1Invocation {
+    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 V1InvocationResponse {
+    data: V1Invocation;
+}
+export interface V1InvocationWaitRequest {
+    timeoutMs?: number;
+}
+export interface V1InvocationWaitResponse {
+    data: V1Invocation;
+    timedOut: boolean;
+}
+export type V1RuntimeInvocationFileInput = {
+    storagePath: string;
+    name?: string;
+} | {
+    fileId: string;
+    name?: string;
+};
+interface V1RuntimeInvocationAgentFields {
+    target?: JsonObject;
+    idempotencyKey?: string;
+    outputSchema?: JsonObject;
+    toolsetId?: string;
+    metadata?: JsonObject;
+    files?: V1RuntimeInvocationFileInput[];
+}
+export type V1RuntimeInvocationCreateRequest = {
+    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;
+} | (V1RuntimeInvocationAgentFields & {
+    provider: 'stagehand';
+    method: 'agent';
+    input: JsonObject;
+    config?: JsonObject;
+    options?: JsonObject;
+}) | (V1RuntimeInvocationAgentFields & {
+    provider: 'browserUse';
+    method: 'agent';
+    input: JsonObject;
+    config?: JsonObject;
+    options?: JsonObject;
+}) | {
+    provider: 'bctrl';
+    method: 'solveCaptcha';
+    target?: JsonObject;
+    input?: JsonObject;
+    idempotencyKey?: string;
+    metadata?: JsonObject;
+};
+export interface V1File {
+    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 V1FilesListQuery extends V1PageQuery {
+    spaceId: string;
+    source?: 'upload' | 'runtime' | 'system';
+    path?: string;
+    prefix?: string;
+    query?: string;
+    contentType?: string;
+}
+export interface V1FileUpdateRequest {
+    name?: string;
+    metadata?: JsonObject | null;
+}
+export interface V1FileDeleteResponse {
+    success: true;
+}
+export interface V1FileUploadRequest {
+    spaceId: string;
+    file: Blob;
+    name?: string;
+    path?: string;
+    metadata?: JsonObject;
+}
+export interface V1RunFilesListQuery extends V1PageQuery {
+    type?: string | string[];
+}
+export interface V1RunFilesExportRequest {
+    format: 'zip';
+    name: string;
+    filter?: {
+        type?: string[];
+    };
+}
+export type V1RuntimeFileStageRequest = {
+    storagePath: string;
+    name?: string;
+} | {
+    fileId: string;
+    name?: string;
+};
+export interface V1RuntimeStagedFile {
+    id: string;
+    runtimeId: string;
+    runtimePath: string;
+    name: string;
+    sizeBytes: number;
+    expiresAt: string | null;
+}
+export interface V1RuntimeFileUploadRequest {
+    file: Blob;
+    name?: string;
+    storagePath?: string;
+    metadata?: JsonObject;
+}
+export interface V1RuntimeFileUploadResponse {
+    file: V1File;
+    staged: V1RuntimeStagedFile;
+}
+export interface V1RuntimeFileCollectRequest {
+    path: string;
+    storagePath?: string;
+    name?: string;
+    artifact?: {
+        kind?: string;
+        name?: string;
+        metadata?: JsonObject;
+    };
+}
+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.3",
   "description": "BCTRL SDK - Remote browser automation",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -9,22 +9,6 @@
     ".": {
       "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": {
@@ -32,6 +16,9 @@
     "build": "pnpm run clean && tsc -p tsconfig.json",
     "prepack": "pnpm run build",
     "dev": "tsc --watch",
+    "test": "tsx --test tests/v1/*.test.ts tests/v1/e2e/*.test.ts",
+    "test:v1": "tsx --test tests/v1/*.test.ts tests/v1/e2e/*.test.ts",
+    "test:v1:e2e": "BCTRL_E2E=1 tsx --test tests/v1/e2e/**/*.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "keywords": [],
@@ -46,10 +33,6 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
-  "dependencies": {
-    "@sentry/node": "^10.38.0",
-    "zod": "^4.2.1"
-  },
   "files": [
     "dist"
   ]

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';