@bctrl/sdk 1.0.1 → 1.0.3

package/README.md

@@ -1,6 +1,6 @@
 # @bctrl/sdk
 
-TypeScript SDK for BCTRL workspaces, browser runtimes, and browser profile automation.
+TypeScript SDK for BCTRL v1 spaces, browser runtimes, invocations, runs, and files.
 
 ## Install
 
@@ -19,44 +19,48 @@ 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 runtime = await space.runtimes.create({
+  type: 'browser',
+  name: 'browser-task',
+  config: {
+    browser: { profile: false },
+  },
 });
+const { runtime: browser } = await runtime.start();
 
-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/v1`. For local development, pass a
+local origin or v1 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 `/v1`; 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`: v1 client, resources, errors, and public types
 
 ## Documentation
 
@@ -65,11 +69,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 { V1FilesClient } from './files.js';
+import { type V1ClientOptions } from './http.js';
+import { V1InvocationsClient } from './invocations.js';
+import { V1RunsClient } from './runs.js';
+import { V1RuntimesClient } from './runtimes.js';
+import { V1SpacesClient } from './spaces.js';
+export type BctrlV1Options = V1ClientOptions;
+export declare class BctrlV1 {
+    private readonly http;
+    private _spaces;
+    private _runtimes;
+    private _runs;
+    private _invocations;
+    private _files;
+    static isControllerBusy(error: unknown): boolean;
+    constructor(options?: BctrlV1Options);
+    get spaces(): V1SpacesClient;
+    get runtimes(): V1RuntimesClient;
+    get runs(): V1RunsClient;
+    get invocations(): V1InvocationsClient;
+    get files(): V1FilesClient;
 }
-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 { BctrlV1 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 { V1FilesClient } from './files.js';
+import { V1HttpClient } from './http.js';
+import { V1InvocationsClient } from './invocations.js';
+import { V1RunsClient } from './runs.js';
+import { V1RuntimesClient } from './runtimes.js';
+import { V1SpacesClient } from './spaces.js';
+export class BctrlV1 {
+    http;
+    _spaces = null;
+    _runtimes = null;
+    _runs = null;
+    _invocations = null;
+    _files = null;
+    static isControllerBusy(error) {
+        return isControllerBusy(error);
+    }
+    constructor(options = {}) {
+        this.http = new V1HttpClient(options);
+    }
+    get spaces() {
+        this._spaces ??= new V1SpacesClient(this.http);
+        return this._spaces;
+    }
+    get runtimes() {
+        this._runtimes ??= new V1RuntimesClient(this.http);
+        return this._runtimes;
+    }
+    get runs() {
+        this._runs ??= new V1RunsClient(this.http);
+        return this._runs;
+    }
+    get invocations() {
+        this._invocations ??= new V1InvocationsClient(this.http);
+        return this._invocations;
+    }
+    get files() {
+        this._files ??= new V1FilesClient(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 { BctrlV1 as Bctrl };

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 V1ErrorContext {
+    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?: V1ErrorContext;
+    constructor(message: string, code: string, context?: V1ErrorContext);
     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?: V1ErrorContext);
+    get status(): number | undefined;
+    get requestId(): string | undefined;
+}
+export declare class BctrlAuthenticationError extends BctrlApiError {
+    constructor(message: string, code?: string, context?: V1ErrorContext);
+}
+export declare class BctrlPermissionError extends BctrlApiError {
+    constructor(message: string, code?: string, context?: V1ErrorContext);
+}
+export declare class BctrlNotFoundError extends BctrlApiError {
+    constructor(message: string, code?: string, context?: V1ErrorContext);
+}
+export declare class BctrlConflictError extends BctrlApiError {
+    constructor(message: string, code?: string, context?: V1ErrorContext);
+}
+export declare class BctrlRateLimitError extends BctrlApiError {
+    constructor(message: string, code?: string, context?: V1ErrorContext);
+}
+export declare class BctrlValidationError extends BctrlApiError {
+    constructor(message: string, code?: string, context?: V1ErrorContext);
+}
+export declare class BctrlNetworkError extends BctrlError {
+    constructor(message: string, context?: V1ErrorContext);
+}
+export declare class BctrlNotReadyError extends BctrlError {
+    constructor(message: string, context?: V1ErrorContext);
+}
+export declare class BctrlUnsupportedError extends BctrlError {
+    constructor(message: string, context?: V1ErrorContext);
+}
+export declare function createV1HttpError(input: {
+    status: number;
+    message: string;
+    code?: string;
+    requestId?: string;
+    body?: unknown;
+}): BctrlApiError;
+export declare function isControllerBusy(error: unknown): boolean;

package/dist/errors.js

@@ -1,157 +1,120 @@
-// ============================================================================
-// 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.name = 'BctrlError';
         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,
+            ...(this.context ? { context: this.context } : {}),
         };
     }
 }
-/** Automation/driver/script errors — your code or selectors need fixing */
-export class AutomationError extends BctrlError {
-    constructor(message, code = 'DRIVER_ERROR', context) {
+export class BctrlApiError extends BctrlError {
+    constructor(message, code = 'api.error', context) {
         super(message, code, context);
-        this.name = 'AutomationError';
+        this.name = 'BctrlApiError';
     }
-    /** Human-readable suggestion from control-plane validation. */
-    get hint() {
-        return getContextHint(this.context);
+    get status() {
+        return typeof this.context?.status === 'number' ? this.context.status : undefined;
     }
-    /** Structured diagnostic payload with machine-readable fix metadata. */
-    get diagnostic() {
-        return getContextDiagnostic(this.context);
+    get requestId() {
+        return typeof this.context?.requestId === 'string' ? this.context.requestId : undefined;
     }
 }
-/** Session/browser lifecycle errors — reconnect or recreate */
-export class SessionError extends BctrlError {
-    constructor(message, code = 'SESSION_ERROR', context) {
+export class BctrlAuthenticationError extends BctrlApiError {
+    constructor(message, code = 'auth.error', context) {
         super(message, code, context);
-        this.name = 'SessionError';
+        this.name = 'BctrlAuthenticationError';
     }
 }
-/** Timeout errors — increase timeout or retry */
-export class TimeoutError extends BctrlError {
-    constructor(message, context) {
-        super(message, 'TIMEOUT_ERROR', context);
-        this.name = 'TimeoutError';
+export class BctrlPermissionError extends BctrlApiError {
+    constructor(message, code = 'permission.denied', context) {
+        super(message, code, context);
+        this.name = 'BctrlPermissionError';
     }
 }
-/** Authentication/authorization errors — check API key */
-export class AuthenticationError extends BctrlError {
-    constructor(message, context) {
-        super(message, 'AUTH_ERROR', context);
-        this.name = 'AuthenticationError';
+export class BctrlNotFoundError extends BctrlApiError {
+    constructor(message, code = 'resource.not_found', context) {
+        super(message, code, context);
+        this.name = 'BctrlNotFoundError';
     }
 }
-// ============================================================================
-// 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);
+export class BctrlConflictError extends BctrlApiError {
+    constructor(message, code = 'resource.conflict', context) {
+        super(message, code, context);
+        this.name = 'BctrlConflictError';
     }
 }
-// ============================================================================
-// 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 class BctrlRateLimitError extends BctrlApiError {
+    constructor(message, code = 'rate_limit.exceeded', context) {
+        super(message, code, context);
+        this.name = 'BctrlRateLimitError';
+    }
 }
-export function isAutomationError(error) {
-    return error instanceof AutomationError || (isBctrlError(error) && error.name === 'AutomationError');
+export class BctrlValidationError extends BctrlApiError {
+    constructor(message, code = 'validation.error', context) {
+        super(message, code, context);
+        this.name = 'BctrlValidationError';
+    }
 }
-export function isSessionError(error) {
-    return error instanceof SessionError || (isBctrlError(error) && error.name === 'SessionError');
+export class BctrlNetworkError extends BctrlError {
+    constructor(message, context) {
+        super(message, 'network.error', context);
+        this.name = 'BctrlNetworkError';
+    }
 }
-export function isTimeoutError(error) {
-    return error instanceof TimeoutError || (isBctrlError(error) && error.name === 'TimeoutError');
+export class BctrlNotReadyError extends BctrlError {
+    constructor(message, context) {
+        super(message, 'runtime.not_ready', context);
+        this.name = 'BctrlNotReadyError';
+    }
 }
-export function isAuthenticationError(error) {
-    return error instanceof AuthenticationError || (isBctrlError(error) && error.name === 'AuthenticationError');
+export class BctrlUnsupportedError extends BctrlError {
+    constructor(message, context) {
+        super(message, 'sdk.unsupported', context);
+        this.name = 'BctrlUnsupportedError';
+    }
 }
-/**
- * Get a typed automation hint from an SDK error when available.
- */
-export function getAutomationHint(error) {
-    if (!isBctrlError(error))
-        return undefined;
-    return getContextHint(error.context);
+export function createV1HttpError(input) {
+    const context = {
+        status: input.status,
+        requestId: input.requestId,
+        body: input.body,
+    };
+    const code = input.code;
+    if (code)
+        context.code = code;
+    if (input.status === 401) {
+        return new BctrlAuthenticationError(input.message, code, context);
+    }
+    if (input.status === 403) {
+        return new BctrlPermissionError(input.message, code, context);
+    }
+    if (input.status === 404) {
+        return new BctrlNotFoundError(input.message, code, context);
+    }
+    if (input.status === 409) {
+        return new BctrlConflictError(input.message, code, context);
+    }
+    if (input.status === 422 || input.status === 400) {
+        return new BctrlValidationError(input.message, code, context);
+    }
+    if (input.status === 429) {
+        return new BctrlRateLimitError(input.message, code, context);
+    }
+    return new BctrlApiError(input.message, code, 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);
+export function isControllerBusy(error) {
+    if (!(error instanceof BctrlError)) {
+        return false;
+    }
+    const code = error.code.toLowerCase();
+    return code.includes('controller') && code.includes('busy');
 }

package/dist/files.d.ts

@@ -0,0 +1,31 @@
+import type { V1HttpClient } from './http.js';
+import type { V1File, V1FileDeleteResponse, V1FilesListQuery, V1FileUpdateRequest, V1FileUploadRequest, V1ListEnvelope, V1RunFilesExportRequest, V1RunFilesListQuery } from './types.js';
+export declare class V1FileResource {
+    private readonly http;
+    readonly data: V1File;
+    constructor(http: V1HttpClient, data: V1File);
+    get id(): string;
+    refresh(): Promise<V1FileResource>;
+    content(): Promise<Response>;
+    update(request: V1FileUpdateRequest): Promise<V1FileResource>;
+    delete(): Promise<V1FileDeleteResponse>;
+}
+export declare class V1FilesClient {
+    private readonly http;
+    constructor(http: V1HttpClient);
+    list(query: V1FilesListQuery): Promise<V1ListEnvelope<V1File>>;
+    iter(query: V1FilesListQuery): AsyncGenerator<V1File, void, undefined>;
+    get(id: string): Promise<V1FileResource>;
+    update(id: string, request: V1FileUpdateRequest): Promise<V1FileResource>;
+    content(id: string): Promise<Response>;
+    delete(id: string): Promise<V1FileDeleteResponse>;
+    upload(request: V1FileUploadRequest): Promise<V1FileResource>;
+}
+export declare class V1RunFilesClient {
+    private readonly http;
+    private readonly runId;
+    constructor(http: V1HttpClient, runId: string);
+    list(query?: V1RunFilesListQuery): Promise<V1ListEnvelope<V1File>>;
+    iter(query?: V1RunFilesListQuery): AsyncGenerator<V1File, void, undefined>;
+    export(request: V1RunFilesExportRequest): Promise<V1FileResource>;
+}