@bctrl/sdk 1.0.1 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @bctrl/sdk
 
-TypeScript SDK for BCTRL workspaces, browser runtimes, and browser profile automation.
+TypeScript SDK for BCTRL v2 spaces, browser runtimes, invocations, runs, and files.
 
 ## Install
 
@@ -19,44 +19,44 @@ const bctrl = new Bctrl({
   apiKey: process.env.BCTRL_API_KEY!,
 });
 
-const workspace = await bctrl.workspaces.create({
+const space = await bctrl.spaces.create({
   name: 'my-task',
+  region: 'us-east-1',
 });
 
-const browser = await workspace.runtimes.browser('web').playwright({
-  launch: { mode: 'ephemeral' },
+const browser = await space.browsers.launch({
+  name: 'browser-task',
+  state: 'ephemeral',
 });
 
-await browser.run({
-  steps: [
-    { call: 'page.goto', args: ['https://example.com'] },
-  ],
+const connection = await browser.connect();
+console.log(connection.wsUrl);
+
+const invocation = await browser.invocations.create({
+  provider: 'stagehand',
+  method: 'act',
+  input: { instruction: 'Open https://example.com' },
 });
 
-const state = await workspace.state({ runtime: 'web' });
-console.log(state.runtimes[0]?.summary);
+const result = await invocation.wait({ timeoutMs: 60_000 });
+console.log(result.data.status);
 ```
 
-The public SDK always targets `https://api.bctrl.ai/v1`.
-
-For local development inside this repo, use the internal test helper instead of changing the public client base URL:
+The public SDK targets `https://api.bctrl.ai/v2`. For local development, pass a
+local origin or v2 base URL:
 
 ```ts
-import { createInternalBctrl } from '../src/internal/dev-client.js';
-
-const bctrl = createInternalBctrl({
+const bctrl = new Bctrl({
   apiKey: process.env.BCTRL_API_KEY!,
-  apiOrigin: 'http://localhost:8787',
+  baseUrl: 'http://localhost:8787',
 });
 ```
 
+`baseUrl` may include or omit `/v2`; the client normalizes either form.
+
 ## Entry points
 
-- `@bctrl/sdk`: core client, workspaces, browser profiles, AI credentials, storage, vault, updates
-- `@bctrl/sdk/playwright`: Playwright driver types and remote browser classes
-- `@bctrl/sdk/puppeteer`: Puppeteer driver types and remote browser classes
-- `@bctrl/sdk/stagehand`: Stagehand driver types and remote browser classes
-- `@bctrl/sdk/selenium`: Selenium driver types and remote browser classes
+- `@bctrl/sdk`: v2 client, resources, errors, and public types
 
 ## Documentation
 
@@ -65,11 +65,6 @@ const bctrl = createInternalBctrl({
 
 ## Telemetry
 
-The SDK currently contains optional error telemetry, not full usage analytics.
-
-- Error reporting is Sentry-based and only activates when `SENTRY_DSN_SDK` is present at runtime.
-- It captures SDK errors such as request timeouts and failed HTTP or automation calls.
-- Sensitive headers like `authorization`, `cookie`, and internal secrets are stripped before an event is sent.
-- Pass `telemetry: false` to `new Bctrl(...)` to disable it explicitly.
+The published SDK does not include vendor-owned telemetry or usage analytics.
 
-If you want to measure feature adoption, successful operations, or per-method usage, that is not implemented in the published SDK today. Instrument your application around SDK calls or add explicit SDK hooks before relying on package-level usage analytics.
+If you want observability around SDK calls, instrument your application directly with your own logging or error tracking.

package/dist/bctrl.d.ts

@@ -1,37 +1,23 @@
-import { AiCredentialsClient } from './ai-credentials/client.js';
-import { BrowserExtensionsClient } from './browser-extensions/client.js';
-import { BrowserProfilesClient } from './browser-profiles/client.js';
-import { StorageClient } from './storage/client.js';
-import { UpdatesClient } from './updates/client.js';
-import { VaultClient } from './vault/client.js';
-import { WorkspacesClient } from './workspaces/client.js';
-declare const INTERNAL_BASE_URL: unique symbol;
-export interface BctrlOptions {
-    apiKey: string;
-    telemetry?: boolean;
+import { V2FilesClient } from './files.js';
+import { type V2ClientOptions } from './http.js';
+import { V2InvocationsClient } from './invocations.js';
+import { V2RunsClient } from './runs.js';
+import { V2RuntimesClient } from './runtimes.js';
+import { V2SpacesClient } from './spaces.js';
+export type BctrlV2Options = V2ClientOptions;
+export declare class BctrlV2 {
+    private readonly http;
+    private _spaces;
+    private _runtimes;
+    private _runs;
+    private _invocations;
+    private _files;
+    static isControllerBusy(error: unknown): boolean;
+    constructor(options?: BctrlV2Options);
+    get spaces(): V2SpacesClient;
+    get runtimes(): V2RuntimesClient;
+    get runs(): V2RunsClient;
+    get invocations(): V2InvocationsClient;
+    get files(): V2FilesClient;
 }
-type InternalBctrlOverride = {
-    [INTERNAL_BASE_URL]: string;
-};
-export declare class Bctrl {
-    private readonly baseUrl;
-    private readonly apiKey;
-    private _aiCredentials;
-    private _browserExtensions;
-    private _browserProfiles;
-    private _vault;
-    private _workspaces;
-    private _updates;
-    constructor(options: BctrlOptions, internalOverride?: InternalBctrlOverride);
-    get aiCredentials(): AiCredentialsClient;
-    get browserProfiles(): BrowserProfilesClient;
-    get browserExtensions(): BrowserExtensionsClient;
-    storage(workspace: string): StorageClient;
-    get vault(): VaultClient;
-    get workspaces(): WorkspacesClient;
-    get updates(): UpdatesClient;
-}
-export declare function createInternalBctrlClient(options: BctrlOptions & {
-    apiBaseUrl: string;
-}): Bctrl;
-export {};
+export { BctrlV2 as Bctrl };

package/dist/bctrl.js

@@ -1,77 +1,42 @@
-import * as telemetry from './telemetry.js';
-import { AiCredentialsClient } from './ai-credentials/client.js';
-import { BrowserExtensionsClient } from './browser-extensions/client.js';
-import { BrowserProfilesClient } from './browser-profiles/client.js';
-import { resolveApiKey, resolveProductionApiBaseUrl } from './config.js';
-import { StorageClient } from './storage/client.js';
-import { UpdatesClient } from './updates/client.js';
-import { VaultClient } from './vault/client.js';
-import { WorkspacesClient } from './workspaces/client.js';
-const INTERNAL_BASE_URL = Symbol('bctrl.internalBaseUrl');
-export class Bctrl {
-    baseUrl;
-    apiKey;
-    _aiCredentials = null;
-    _browserExtensions = null;
-    _browserProfiles = null;
-    _vault = null;
-    _workspaces = null;
-    _updates = null;
-    constructor(options, internalOverride) {
-        this.apiKey = resolveApiKey(options.apiKey);
-        this.baseUrl = internalOverride?.[INTERNAL_BASE_URL] ?? resolveProductionApiBaseUrl();
-        if (options.telemetry === false) {
-            telemetry.disable();
-        }
-        else {
-            telemetry.init();
-        }
+import { isControllerBusy } from './errors.js';
+import { V2FilesClient } from './files.js';
+import { V2HttpClient } from './http.js';
+import { V2InvocationsClient } from './invocations.js';
+import { V2RunsClient } from './runs.js';
+import { V2RuntimesClient } from './runtimes.js';
+import { V2SpacesClient } from './spaces.js';
+export class BctrlV2 {
+    http;
+    _spaces = null;
+    _runtimes = null;
+    _runs = null;
+    _invocations = null;
+    _files = null;
+    static isControllerBusy(error) {
+        return isControllerBusy(error);
+    }
+    constructor(options = {}) {
+        this.http = new V2HttpClient(options);
+    }
+    get spaces() {
+        this._spaces ??= new V2SpacesClient(this.http);
+        return this._spaces;
+    }
+    get runtimes() {
+        this._runtimes ??= new V2RuntimesClient(this.http);
+        return this._runtimes;
+    }
+    get runs() {
+        this._runs ??= new V2RunsClient(this.http);
+        return this._runs;
+    }
+    get invocations() {
+        this._invocations ??= new V2InvocationsClient(this.http);
+        return this._invocations;
+    }
+    get files() {
+        this._files ??= new V2FilesClient(this.http);
+        return this._files;
     }
-    get aiCredentials() {
-        if (!this._aiCredentials) {
-            this._aiCredentials = new AiCredentialsClient(this.baseUrl, this.apiKey);
-        }
-        return this._aiCredentials;
-    }
-    get browserProfiles() {
-        if (!this._browserProfiles) {
-            this._browserProfiles = new BrowserProfilesClient(this.baseUrl, this.apiKey);
-        }
-        return this._browserProfiles;
-    }
-    get browserExtensions() {
-        if (!this._browserExtensions) {
-            this._browserExtensions = new BrowserExtensionsClient(this.baseUrl, this.apiKey);
-        }
-        return this._browserExtensions;
-    }
-    storage(workspace) {
-        return new StorageClient(this.baseUrl, workspace, this.apiKey);
-    }
-    get vault() {
-        if (!this._vault) {
-            this._vault = new VaultClient(this.baseUrl, this.apiKey);
-        }
-        return this._vault;
-    }
-    get workspaces() {
-        if (!this._workspaces) {
-            this._workspaces = new WorkspacesClient(this.baseUrl, this.apiKey);
-        }
-        return this._workspaces;
-    }
-    get updates() {
-        if (!this._updates) {
-            this._updates = new UpdatesClient(this.baseUrl, this.apiKey);
-        }
-        return this._updates;
-    }
-}
-export function createInternalBctrlClient(options) {
-    return new Bctrl({
-        apiKey: options.apiKey,
-        telemetry: options.telemetry,
-    }, {
-        [INTERNAL_BASE_URL]: options.apiBaseUrl,
-    });
 }
+export { BctrlV2 as Bctrl };

package/dist/browsers.d.ts

@@ -0,0 +1,24 @@
+import type { V2HttpClient } from './http.js';
+import type { V2RuntimeInvocationsClient } from './invocations.js';
+import { V2RuntimeConnectionResource, V2RuntimeResource } from './runtimes.js';
+import { V2RunResource } from './runs.js';
+import type { BrowserLaunchOptions, V2Runtime, V2RuntimeConnectionCreateOptions } from './types.js';
+export declare class V2BrowserResource {
+    private readonly http;
+    private readonly spaceId;
+    readonly runtime: V2RuntimeResource;
+    constructor(http: V2HttpClient, spaceId: string, runtime: V2RuntimeResource);
+    get id(): string;
+    get data(): V2Runtime;
+    get invocations(): V2RuntimeInvocationsClient;
+    connect(request?: V2RuntimeConnectionCreateOptions): Promise<V2RuntimeConnectionResource>;
+    run(): Promise<V2RunResource>;
+    stop(): Promise<V2Runtime>;
+    refresh(): Promise<V2BrowserResource>;
+}
+export declare class V2SpaceBrowsersClient {
+    private readonly http;
+    private readonly spaceId;
+    constructor(http: V2HttpClient, spaceId: string);
+    launch(options: BrowserLaunchOptions): Promise<V2BrowserResource>;
+}

package/dist/browsers.js

@@ -0,0 +1,82 @@
+import { BctrlValidationError } from './errors.js';
+import { V2RuntimesClient, } from './runtimes.js';
+export class V2BrowserResource {
+    http;
+    spaceId;
+    runtime;
+    constructor(http, spaceId, runtime) {
+        this.http = http;
+        this.spaceId = spaceId;
+        this.runtime = runtime;
+    }
+    get id() {
+        return this.runtime.id;
+    }
+    get data() {
+        return this.runtime.data;
+    }
+    get invocations() {
+        return this.runtime.invocations;
+    }
+    connect(request) {
+        return this.runtime.connect(request);
+    }
+    async run() {
+        return this.runtime.run();
+    }
+    stop() {
+        return this.runtime.stop();
+    }
+    async refresh() {
+        const runtime = await new V2RuntimesClient(this.http).get(this.id);
+        return new V2BrowserResource(this.http, this.spaceId, runtime);
+    }
+}
+export class V2SpaceBrowsersClient {
+    http;
+    spaceId;
+    constructor(http, spaceId) {
+        this.http = http;
+        this.spaceId = spaceId;
+    }
+    async launch(options) {
+        const request = browserLaunchToRuntimeCreate(options);
+        const runtime = await new V2RuntimesClient(this.http).createInSpace(this.spaceId, request);
+        const started = await runtime.start();
+        return new V2BrowserResource(this.http, this.spaceId, started.runtime);
+    }
+}
+function browserLaunchToRuntimeCreate(options) {
+    const state = options.state ?? 'ephemeral';
+    if (!options.name?.trim()) {
+        throw new BctrlValidationError('Browser name is required', 'browser.name_required');
+    }
+    if (state === 'profile') {
+        const unsupported = [
+            ['stealth', options.stealth],
+            ['proxy', options.proxy],
+            ['fingerprint', options.fingerprint],
+            ['extensions', options.extensions],
+        ]
+            .filter(([, value]) => value !== undefined)
+            .map(([key]) => key);
+        if (unsupported.length > 0) {
+            throw new BctrlValidationError('Profile-backed browser launch only supports lifecycle config right now', 'browser.profile_config_unsupported', { unsupported });
+        }
+    }
+    return {
+        type: 'browser',
+        name: options.name,
+        metadata: options.metadata,
+        config: {
+            browser: {
+                profile: state === 'profile',
+            },
+            ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
+            ...(state === 'ephemeral' && options.stealth ? { stealth: options.stealth } : {}),
+            ...(state === 'ephemeral' && options.proxy !== undefined ? { proxy: options.proxy } : {}),
+            ...(state === 'ephemeral' && options.fingerprint ? { fingerprint: options.fingerprint } : {}),
+            ...(state === 'ephemeral' && options.extensions ? { extensions: options.extensions } : {}),
+        },
+    };
+}

package/dist/errors.d.ts

@@ -1,47 +1,53 @@
-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 interface V2ErrorContext {
+    status?: number;
+    code?: string;
+    requestId?: string;
+    body?: unknown;
+    [key: string]: unknown;
+}
 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() */
+    readonly context?: V2ErrorContext;
+    constructor(message: string, code: string, context?: V2ErrorContext);
     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;
+export declare class BctrlApiError extends BctrlError {
+    constructor(message: string, code?: string, context?: V2ErrorContext);
+    get status(): number | undefined;
+    get requestId(): string | undefined;
+}
+export declare class BctrlAuthenticationError extends BctrlApiError {
+    constructor(message: string, code?: string, context?: V2ErrorContext);
+}
+export declare class BctrlPermissionError extends BctrlApiError {
+    constructor(message: string, code?: string, context?: V2ErrorContext);
+}
+export declare class BctrlNotFoundError extends BctrlApiError {
+    constructor(message: string, code?: string, context?: V2ErrorContext);
+}
+export declare class BctrlConflictError extends BctrlApiError {
+    constructor(message: string, code?: string, context?: V2ErrorContext);
+}
+export declare class BctrlRateLimitError extends BctrlApiError {
+    constructor(message: string, code?: string, context?: V2ErrorContext);
+}
+export declare class BctrlValidationError extends BctrlApiError {
+    constructor(message: string, code?: string, context?: V2ErrorContext);
+}
+export declare class BctrlNetworkError extends BctrlError {
+    constructor(message: string, context?: V2ErrorContext);
+}
+export declare class BctrlNotReadyError extends BctrlError {
+    constructor(message: string, context?: V2ErrorContext);
+}
+export declare class BctrlUnsupportedError extends BctrlError {
+    constructor(message: string, context?: V2ErrorContext);
+}
+export declare function createV2HttpError(input: {
+    status: number;
+    message: string;
+    code?: string;
+    requestId?: string;
+    body?: unknown;
+}): BctrlApiError;
+export declare function isControllerBusy(error: unknown): boolean;