@bctrl/sdk 1.0.1 → 1.0.2

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 createV2HttpError(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 { V2HttpClient } from './http.js';
+import type { V2File, V2FileDeleteResponse, V2FilesListQuery, V2FileUpdateRequest, V2FileUploadRequest, V2ListEnvelope, V2RunFilesExportRequest, V2RunFilesListQuery } from './types.js';
+export declare class V2FileResource {
+    private readonly http;
+    readonly data: V2File;
+    constructor(http: V2HttpClient, data: V2File);
+    get id(): string;
+    refresh(): Promise<V2FileResource>;
+    content(): Promise<Response>;
+    update(request: V2FileUpdateRequest): Promise<V2FileResource>;
+    delete(): Promise<V2FileDeleteResponse>;
+}
+export declare class V2FilesClient {
+    private readonly http;
+    constructor(http: V2HttpClient);
+    list(query: V2FilesListQuery): Promise<V2ListEnvelope<V2File>>;
+    iter(query: V2FilesListQuery): AsyncGenerator<V2File, void, undefined>;
+    get(id: string): Promise<V2FileResource>;
+    update(id: string, request: V2FileUpdateRequest): Promise<V2FileResource>;
+    content(id: string): Promise<Response>;
+    delete(id: string): Promise<V2FileDeleteResponse>;
+    upload(request: V2FileUploadRequest): Promise<V2FileResource>;
+}
+export declare class V2RunFilesClient {
+    private readonly http;
+    private readonly runId;
+    constructor(http: V2HttpClient, runId: string);
+    list(query?: V2RunFilesListQuery): Promise<V2ListEnvelope<V2File>>;
+    iter(query?: V2RunFilesListQuery): AsyncGenerator<V2File, void, undefined>;
+    export(request: V2RunFilesExportRequest): Promise<V2FileResource>;
+}

package/dist/files.js

@@ -0,0 +1,97 @@
+import { iterateV2Pages } from './pagination.js';
+export class V2FileResource {
+    http;
+    data;
+    constructor(http, data) {
+        this.http = http;
+        this.data = data;
+    }
+    get id() {
+        return this.data.id;
+    }
+    refresh() {
+        return new V2FilesClient(this.http).get(this.id);
+    }
+    async content() {
+        return new V2FilesClient(this.http).content(this.id);
+    }
+    async update(request) {
+        return new V2FilesClient(this.http).update(this.id, request);
+    }
+    delete() {
+        return new V2FilesClient(this.http).delete(this.id);
+    }
+}
+export class V2FilesClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(query) {
+        return this.http.request('/files', { query });
+    }
+    iter(query) {
+        return iterateV2Pages(query, (pageQuery) => this.list(pageQuery));
+    }
+    async get(id) {
+        const file = await this.http.request(`/files/${encodeURIComponent(id)}`);
+        return new V2FileResource(this.http, file);
+    }
+    async update(id, request) {
+        const file = await this.http.request(`/files/${encodeURIComponent(id)}`, {
+            method: 'PATCH',
+            body: request,
+        });
+        return new V2FileResource(this.http, file);
+    }
+    content(id) {
+        return this.http.raw(`/files/${encodeURIComponent(id)}/content`);
+    }
+    delete(id) {
+        return this.http.request(`/files/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+        });
+    }
+    async upload(request) {
+        const form = new FormData();
+        if (request.name) {
+            form.set('file', request.file, request.name);
+        }
+        else {
+            form.set('file', request.file);
+        }
+        if (request.name)
+            form.set('name', request.name);
+        if (request.path)
+            form.set('path', request.path);
+        if (request.metadata)
+            form.set('metadata', JSON.stringify(request.metadata));
+        const file = await this.http.request('/files', {
+            method: 'POST',
+            query: { spaceId: request.spaceId },
+            body: form,
+        });
+        return new V2FileResource(this.http, file);
+    }
+}
+export class V2RunFilesClient {
+    http;
+    runId;
+    constructor(http, runId) {
+        this.http = http;
+        this.runId = runId;
+    }
+    list(query = {}) {
+        return this.http.request(`/runs/${encodeURIComponent(this.runId)}/files`, { query });
+    }
+    iter(query = {}) {
+        return iterateV2Pages(query, (pageQuery) => this.list(pageQuery));
+    }
+    async export(request) {
+        const file = await this.http.request(`/runs/${encodeURIComponent(this.runId)}/files/export`, {
+            method: 'POST',
+            body: request,
+        });
+        return new V2FileResource(this.http, file);
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,18 @@
+export interface V2ClientOptions {
+    apiKey?: string;
+    baseUrl?: string;
+}
+export interface V2RequestOptions {
+    method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    query?: object;
+    body?: unknown;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
+export declare class V2HttpClient {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    constructor(options: V2ClientOptions);
+    request<T>(path: string, options?: V2RequestOptions): Promise<T>;
+    raw(path: string, options?: V2RequestOptions): Promise<Response>;
+}

package/dist/http.js

@@ -0,0 +1,135 @@
+import { BctrlNetworkError, createV2HttpError } from './errors.js';
+import { BCTRL_PRODUCTION_ORIGIN, fetchWithTimeout, resolveApiKey, stripTrailingSlash, } from './utils.js';
+import { SDK_VERSION } from './version.js';
+const V2_PREFIX = '/v2';
+function resolveV2ApiBaseUrl(baseUrl) {
+    const raw = stripTrailingSlash(baseUrl?.trim() || BCTRL_PRODUCTION_ORIGIN);
+    if (raw.endsWith(V2_PREFIX)) {
+        return raw;
+    }
+    if (raw.endsWith('/v1')) {
+        return `${raw.slice(0, -3)}${V2_PREFIX}`;
+    }
+    return `${raw}${V2_PREFIX}`;
+}
+function resolveV2ApiKey(apiKey) {
+    return resolveApiKey(apiKey ?? process.env.BCTRL_API_KEY ?? '');
+}
+function appendQuery(params, key, value) {
+    if (value === undefined) {
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            if (item !== undefined)
+                params.append(key, String(item));
+        }
+        return;
+    }
+    if (typeof value === 'object') {
+        return;
+    }
+    params.set(key, String(value));
+}
+function parseResponseBody(text) {
+    if (!text.trim()) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function responseRequestId(response) {
+    return (response.headers.get('x-request-id') ??
+        response.headers.get('x-bctrl-request-id') ??
+        undefined);
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function parseV2ErrorBody(parsed, fallbackText) {
+    if (isRecord(parsed) && typeof parsed.error === 'string') {
+        return {
+            error: parsed.error,
+            ...(typeof parsed.code === 'string' ? { code: parsed.code } : {}),
+            ...(typeof parsed.requestId === 'string' ? { requestId: parsed.requestId } : {}),
+        };
+    }
+    if (typeof parsed === 'string' && parsed.trim()) {
+        return { error: parsed.trim() };
+    }
+    return { error: fallbackText.trim() || 'Unknown error' };
+}
+function isBodyInit(value) {
+    return (typeof value === 'string' ||
+        value instanceof Blob ||
+        value instanceof FormData ||
+        value instanceof URLSearchParams ||
+        value instanceof ArrayBuffer);
+}
+export class V2HttpClient {
+    baseUrl;
+    apiKey;
+    constructor(options) {
+        this.baseUrl = resolveV2ApiBaseUrl(options.baseUrl);
+        this.apiKey = resolveV2ApiKey(options.apiKey);
+    }
+    async request(path, options = {}) {
+        const response = await this.raw(path, options);
+        const text = await response.text();
+        return parseResponseBody(text);
+    }
+    async raw(path, options = {}) {
+        const url = new URL(`${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`);
+        const query = options.query ?? {};
+        for (const [key, value] of Object.entries(query)) {
+            appendQuery(url.searchParams, key, value);
+        }
+        const headers = {
+            Accept: 'application/json',
+            Authorization: `Bearer ${this.apiKey}`,
+            'x-sdk-version': SDK_VERSION,
+            'User-Agent': `@bctrl/sdk/${SDK_VERSION} v2`,
+            ...options.headers,
+        };
+        const init = {
+            method: options.method ?? 'GET',
+            headers,
+        };
+        if (options.body !== undefined) {
+            if (isBodyInit(options.body)) {
+                init.body = options.body;
+            }
+            else {
+                headers['Content-Type'] = 'application/json';
+                init.body = JSON.stringify(options.body);
+            }
+        }
+        let response;
+        try {
+            response = await fetchWithTimeout(url.toString(), init, options.timeoutMs);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new BctrlNetworkError(error.message, { cause: error });
+            }
+            throw new BctrlNetworkError('Network request failed');
+        }
+        if (!response.ok) {
+            const text = await response.text();
+            const parsed = parseResponseBody(text);
+            const errorBody = parseV2ErrorBody(parsed, text);
+            throw createV2HttpError({
+                status: response.status,
+                message: errorBody.error,
+                code: errorBody.code,
+                requestId: errorBody.requestId ?? responseRequestId(response),
+                body: parsed,
+            });
+        }
+        return response;
+    }
+}

package/dist/index.d.ts

@@ -1,12 +1,9 @@
-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';
+export { Bctrl, BctrlV2, type BctrlV2Options } from './bctrl.js';
+export { BctrlError, BctrlApiError, BctrlAuthenticationError, BctrlConflictError, BctrlNetworkError, BctrlNotFoundError, BctrlNotReadyError, BctrlPermissionError, BctrlRateLimitError, BctrlUnsupportedError, BctrlValidationError, isControllerBusy, } from './errors.js';
+export { V2BrowserResource, V2SpaceBrowsersClient } from './browsers.js';
+export { V2FileResource, V2FilesClient, V2RunFilesClient } from './files.js';
+export { V2InvocationsClient, V2InvocationResource, V2RuntimeInvocationsClient, } from './invocations.js';
+export { V2RuntimeConnectionResource, V2RuntimeConnectionsClient, V2RuntimeFilesClient, V2RuntimeResource, V2RuntimeRunsClient, V2RuntimesClient, } from './runtimes.js';
+export { V2RunCommandsClient, V2RunEventsClient, V2RunResource, V2RunsClient, } from './runs.js';
+export { V2SpaceEnvironmentClient, V2SpaceResource, V2SpaceRuntimesClient, V2SpacesClient, } from './spaces.js';
+export type * from './types.js';

package/dist/index.js

@@ -1,23 +1,8 @@
-// ============================================================================
-// BCTRL SDK - Core Entry Point
-// ============================================================================
-//
-// Keep the root entrypoint lean.
-// Driver-specific classes and types are exposed via subpath exports:
-// - <package>/puppeteer
-// - <package>/playwright
-// - <package>/stagehand
-// - <package>/selenium
-//
-export { z } from 'zod';
-// Core errors
-export { BctrlError, AutomationError, AutomationError as SdkAutomationError, SessionError, TimeoutError, AuthenticationError, fromErrorResponse, isBctrlError, isAutomationError, isSessionError, isTimeoutError, isAuthenticationError, getAutomationHint, } from './errors.js';
-// Service clients
-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 { Bctrl } from './bctrl.js';
+export { Bctrl, BctrlV2 } from './bctrl.js';
+export { BctrlError, BctrlApiError, BctrlAuthenticationError, BctrlConflictError, BctrlNetworkError, BctrlNotFoundError, BctrlNotReadyError, BctrlPermissionError, BctrlRateLimitError, BctrlUnsupportedError, BctrlValidationError, isControllerBusy, } from './errors.js';
+export { V2BrowserResource, V2SpaceBrowsersClient } from './browsers.js';
+export { V2FileResource, V2FilesClient, V2RunFilesClient } from './files.js';
+export { V2InvocationsClient, V2InvocationResource, V2RuntimeInvocationsClient, } from './invocations.js';
+export { V2RuntimeConnectionResource, V2RuntimeConnectionsClient, V2RuntimeFilesClient, V2RuntimeResource, V2RuntimeRunsClient, V2RuntimesClient, } from './runtimes.js';
+export { V2RunCommandsClient, V2RunEventsClient, V2RunResource, V2RunsClient, } from './runs.js';
+export { V2SpaceEnvironmentClient, V2SpaceResource, V2SpaceRuntimesClient, V2SpacesClient, } from './spaces.js';

package/dist/invocations.d.ts

@@ -0,0 +1,24 @@
+import type { V2HttpClient } from './http.js';
+import type { V2Invocation, V2RuntimeInvocationCreateRequest, V2InvocationWaitRequest, V2InvocationWaitResponse } from './types.js';
+export declare class V2InvocationResource {
+    private readonly http;
+    readonly data: V2Invocation;
+    constructor(http: V2HttpClient, data: V2Invocation);
+    get id(): string;
+    refresh(): Promise<V2Invocation>;
+    wait(request?: V2InvocationWaitRequest): Promise<V2InvocationWaitResponse>;
+    cancel(): Promise<V2Invocation>;
+}
+export declare class V2InvocationsClient {
+    private readonly http;
+    constructor(http: V2HttpClient);
+    get(id: string): Promise<V2InvocationResource>;
+    wait(id: string, request?: V2InvocationWaitRequest): Promise<V2InvocationWaitResponse>;
+    cancel(id: string): Promise<V2InvocationResource>;
+}
+export declare class V2RuntimeInvocationsClient {
+    private readonly http;
+    private readonly runtimeId;
+    constructor(http: V2HttpClient, runtimeId: string);
+    create(request: V2RuntimeInvocationCreateRequest): Promise<V2InvocationResource>;
+}