@bctrl/sdk 1.0.1 → 1.0.3

package/dist/files.js

@@ -0,0 +1,97 @@
+import { iterateV1Pages } from './pagination.js';
+export class V1FileResource {
+    http;
+    data;
+    constructor(http, data) {
+        this.http = http;
+        this.data = data;
+    }
+    get id() {
+        return this.data.id;
+    }
+    refresh() {
+        return new V1FilesClient(this.http).get(this.id);
+    }
+    async content() {
+        return new V1FilesClient(this.http).content(this.id);
+    }
+    async update(request) {
+        return new V1FilesClient(this.http).update(this.id, request);
+    }
+    delete() {
+        return new V1FilesClient(this.http).delete(this.id);
+    }
+}
+export class V1FilesClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(query) {
+        return this.http.request('/files', { query });
+    }
+    iter(query) {
+        return iterateV1Pages(query, (pageQuery) => this.list(pageQuery));
+    }
+    async get(id) {
+        const file = await this.http.request(`/files/${encodeURIComponent(id)}`);
+        return new V1FileResource(this.http, file);
+    }
+    async update(id, request) {
+        const file = await this.http.request(`/files/${encodeURIComponent(id)}`, {
+            method: 'PATCH',
+            body: request,
+        });
+        return new V1FileResource(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 V1FileResource(this.http, file);
+    }
+}
+export class V1RunFilesClient {
+    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 iterateV1Pages(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 V1FileResource(this.http, file);
+    }
+}

package/dist/http.d.ts

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

package/dist/http.js

@@ -0,0 +1,135 @@
+import { BctrlNetworkError, createV1HttpError } from './errors.js';
+import { BCTRL_PRODUCTION_ORIGIN, fetchWithTimeout, resolveApiKey, stripTrailingSlash, } from './utils.js';
+import { SDK_VERSION } from './version.js';
+const API_PREFIX = '/v1';
+function resolveV1ApiBaseUrl(baseUrl) {
+    const raw = stripTrailingSlash(baseUrl?.trim() ||
+        process.env.BCTRL_BASE_URL?.trim() ||
+        process.env.BCTRL_API_BASE_URL?.trim() ||
+        BCTRL_PRODUCTION_ORIGIN);
+    if (raw.endsWith(API_PREFIX)) {
+        return raw;
+    }
+    return `${raw}${API_PREFIX}`;
+}
+function resolveV1ApiKey(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 parseV1ErrorBody(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 V1HttpClient {
+    baseUrl;
+    apiKey;
+    constructor(options) {
+        this.baseUrl = resolveV1ApiBaseUrl(options.baseUrl);
+        this.apiKey = resolveV1ApiKey(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} v1`,
+            ...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 = parseV1ErrorBody(parsed, text);
+            throw createV1HttpError({
+                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, BctrlV1, type BctrlV1Options } from './bctrl.js';
+export { BctrlError, BctrlApiError, BctrlAuthenticationError, BctrlConflictError, BctrlNetworkError, BctrlNotFoundError, BctrlNotReadyError, BctrlPermissionError, BctrlRateLimitError, BctrlUnsupportedError, BctrlValidationError, isControllerBusy, } from './errors.js';
+export { V1FileResource, V1FilesClient, V1RunFilesClient } from './files.js';
+export { V1InvocationsClient, V1InvocationResource, V1RuntimeBrowserUseInvocationsClient, V1RuntimeInvocationsClient, V1RuntimeStagehandInvocationsClient, } from './invocations.js';
+export type { BrowserUseAgentOptions, StagehandActOptions, StagehandAgentOptions, StagehandExtractOptions, StagehandObserveOptions, StagehandVariablePrimitive, StagehandVariableValue, StagehandVariables, } from './invocations.js';
+export { V1RuntimeConnectionResource, V1RuntimeConnectionsClient, V1RuntimeFilesClient, V1RuntimeResource, V1RuntimeRunsClient, V1RuntimesClient, } from './runtimes.js';
+export { V1RunCommandsClient, V1RunEventsClient, V1RunResource, V1RunsClient, } from './runs.js';
+export { V1SpaceEnvironmentClient, V1SpaceResource, V1SpaceRuntimesClient, V1SpacesClient, } from './spaces.js';
+export type * from './types.js';

package/dist/index.js

@@ -1,23 +1,7 @@
-// ============================================================================
-// 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, BctrlV1 } from './bctrl.js';
+export { BctrlError, BctrlApiError, BctrlAuthenticationError, BctrlConflictError, BctrlNetworkError, BctrlNotFoundError, BctrlNotReadyError, BctrlPermissionError, BctrlRateLimitError, BctrlUnsupportedError, BctrlValidationError, isControllerBusy, } from './errors.js';
+export { V1FileResource, V1FilesClient, V1RunFilesClient } from './files.js';
+export { V1InvocationsClient, V1InvocationResource, V1RuntimeBrowserUseInvocationsClient, V1RuntimeInvocationsClient, V1RuntimeStagehandInvocationsClient, } from './invocations.js';
+export { V1RuntimeConnectionResource, V1RuntimeConnectionsClient, V1RuntimeFilesClient, V1RuntimeResource, V1RuntimeRunsClient, V1RuntimesClient, } from './runtimes.js';
+export { V1RunCommandsClient, V1RunEventsClient, V1RunResource, V1RunsClient, } from './runs.js';
+export { V1SpaceEnvironmentClient, V1SpaceResource, V1SpaceRuntimesClient, V1SpacesClient, } from './spaces.js';

package/dist/invocations.d.ts

@@ -0,0 +1,86 @@
+import type { V1HttpClient } from './http.js';
+import type { JsonObject, V1Invocation, V1RuntimeInvocationCreateRequest, V1RuntimeInvocationFileInput, V1InvocationWaitRequest, V1InvocationWaitResponse } from './types.js';
+type JsonSchemaLike = JsonObject | {
+    toJSONSchema: () => unknown;
+};
+export type StagehandVariablePrimitive = string | number | boolean;
+export type StagehandVariableValue = StagehandVariablePrimitive | {
+    value: StagehandVariablePrimitive;
+    description?: string;
+};
+export type StagehandVariables = Record<string, StagehandVariableValue>;
+interface RuntimeInvocationCommonOptions {
+    target?: JsonObject;
+    idempotencyKey?: string;
+    metadata?: JsonObject;
+}
+interface RuntimeAgentCommonOptions extends RuntimeInvocationCommonOptions {
+    toolsetId?: string;
+    files?: V1RuntimeInvocationFileInput[];
+    outputSchema?: JsonObject;
+}
+export interface StagehandActOptions extends RuntimeInvocationCommonOptions {
+    instruction: string;
+    timeoutMs?: number;
+}
+export interface StagehandObserveOptions extends RuntimeInvocationCommonOptions {
+    instruction: string;
+    selector?: string;
+    timeoutMs?: number;
+}
+export type StagehandExtractOptions<TSchema extends JsonSchemaLike | undefined = undefined> = RuntimeInvocationCommonOptions & {
+    instruction: string;
+    schema?: TSchema;
+};
+export interface StagehandAgentOptions extends RuntimeAgentCommonOptions {
+    instruction: string;
+    maxSteps?: number;
+    timeoutMs?: number;
+    variables?: StagehandVariables;
+    config?: JsonObject;
+    options?: JsonObject;
+}
+export interface BrowserUseAgentOptions extends RuntimeAgentCommonOptions {
+    instruction: string;
+    maxSteps?: number;
+    config?: JsonObject;
+    options?: JsonObject;
+}
+export declare class V1InvocationResource {
+    private readonly http;
+    readonly data: V1Invocation;
+    constructor(http: V1HttpClient, data: V1Invocation);
+    get id(): string;
+    refresh(): Promise<V1Invocation>;
+    wait(request?: V1InvocationWaitRequest): Promise<V1InvocationWaitResponse>;
+    cancel(): Promise<V1Invocation>;
+}
+export declare class V1InvocationsClient {
+    private readonly http;
+    constructor(http: V1HttpClient);
+    get(id: string): Promise<V1InvocationResource>;
+    wait(id: string, request?: V1InvocationWaitRequest): Promise<V1InvocationWaitResponse>;
+    cancel(id: string): Promise<V1InvocationResource>;
+}
+export declare class V1RuntimeInvocationsClient {
+    private readonly http;
+    private readonly runtimeId;
+    readonly stagehand: V1RuntimeStagehandInvocationsClient;
+    readonly browserUse: V1RuntimeBrowserUseInvocationsClient;
+    constructor(http: V1HttpClient, runtimeId: string);
+    create(request: V1RuntimeInvocationCreateRequest): Promise<V1InvocationResource>;
+}
+export declare class V1RuntimeStagehandInvocationsClient {
+    private readonly invocations;
+    constructor(invocations: V1RuntimeInvocationsClient);
+    act(options: StagehandActOptions): Promise<V1InvocationResource>;
+    observe(options: StagehandObserveOptions): Promise<V1InvocationResource>;
+    extract<TSchema extends JsonSchemaLike | undefined = undefined>(options: StagehandExtractOptions<TSchema>): Promise<V1InvocationResource>;
+    agent(options: StagehandAgentOptions): Promise<V1InvocationResource>;
+}
+export declare class V1RuntimeBrowserUseInvocationsClient {
+    private readonly invocations;
+    constructor(invocations: V1RuntimeInvocationsClient);
+    agent(options: BrowserUseAgentOptions): Promise<V1InvocationResource>;
+}
+export {};

package/dist/invocations.js

@@ -0,0 +1,159 @@
+export class V1InvocationResource {
+    http;
+    data;
+    constructor(http, data) {
+        this.http = http;
+        this.data = data;
+    }
+    get id() {
+        return this.data.id;
+    }
+    refresh() {
+        return this.http
+            .request(`/invocations/${encodeURIComponent(this.id)}`)
+            .then((response) => response.data);
+    }
+    wait(request) {
+        return this.http.request(`/invocations/${encodeURIComponent(this.id)}/wait`, {
+            method: 'POST',
+            body: request ?? {},
+        });
+    }
+    cancel() {
+        return this.http
+            .request(`/invocations/${encodeURIComponent(this.id)}/cancel`, {
+            method: 'POST',
+        })
+            .then((response) => response.data);
+    }
+}
+export class V1InvocationsClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async get(id) {
+        const response = await this.http.request(`/invocations/${encodeURIComponent(id)}`);
+        return new V1InvocationResource(this.http, response.data);
+    }
+    wait(id, request) {
+        return this.http.request(`/invocations/${encodeURIComponent(id)}/wait`, {
+            method: 'POST',
+            body: request ?? {},
+        });
+    }
+    async cancel(id) {
+        const response = await this.http.request(`/invocations/${encodeURIComponent(id)}/cancel`, {
+            method: 'POST',
+        });
+        return new V1InvocationResource(this.http, response.data);
+    }
+}
+export class V1RuntimeInvocationsClient {
+    http;
+    runtimeId;
+    stagehand;
+    browserUse;
+    constructor(http, runtimeId) {
+        this.http = http;
+        this.runtimeId = runtimeId;
+        this.stagehand = new V1RuntimeStagehandInvocationsClient(this);
+        this.browserUse = new V1RuntimeBrowserUseInvocationsClient(this);
+    }
+    async create(request) {
+        const response = await this.http.request(`/runtimes/${encodeURIComponent(this.runtimeId)}/invocations`, {
+            method: 'POST',
+            body: request,
+        });
+        return new V1InvocationResource(this.http, response.data);
+    }
+}
+export class V1RuntimeStagehandInvocationsClient {
+    invocations;
+    constructor(invocations) {
+        this.invocations = invocations;
+    }
+    act(options) {
+        const { instruction, timeoutMs, ...common } = options;
+        return this.invocations.create({
+            provider: 'stagehand',
+            method: 'act',
+            ...common,
+            input: {
+                instruction,
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            },
+        });
+    }
+    observe(options) {
+        const { instruction, selector, timeoutMs, ...common } = options;
+        return this.invocations.create({
+            provider: 'stagehand',
+            method: 'observe',
+            ...common,
+            input: {
+                instruction,
+                ...(selector !== undefined ? { selector } : {}),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            },
+        });
+    }
+    extract(options) {
+        const { instruction, schema, ...common } = options;
+        return this.invocations.create({
+            provider: 'stagehand',
+            method: 'extract',
+            ...common,
+            input: { instruction },
+            ...(schema !== undefined ? { outputSchema: toJsonSchemaObject(schema) } : {}),
+        });
+    }
+    agent(options) {
+        const { instruction, maxSteps, timeoutMs, variables, config, options: agentOptions, ...common } = options;
+        return this.invocations.create({
+            provider: 'stagehand',
+            method: 'agent',
+            ...common,
+            input: {
+                instruction,
+                ...(maxSteps !== undefined ? { maxSteps } : {}),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                ...(variables !== undefined ? { variables } : {}),
+            },
+            ...(config !== undefined ? { config } : {}),
+            ...(agentOptions !== undefined ? { options: agentOptions } : {}),
+        });
+    }
+}
+export class V1RuntimeBrowserUseInvocationsClient {
+    invocations;
+    constructor(invocations) {
+        this.invocations = invocations;
+    }
+    agent(options) {
+        const { instruction, maxSteps, config, options: agentOptions, ...common } = options;
+        return this.invocations.create({
+            provider: 'browserUse',
+            method: 'agent',
+            ...common,
+            input: {
+                instruction,
+                ...(maxSteps !== undefined ? { maxSteps } : {}),
+            },
+            ...(config !== undefined ? { config } : {}),
+            ...(agentOptions !== undefined ? { options: agentOptions } : {}),
+        });
+    }
+}
+function toJsonSchemaObject(schema) {
+    const value = typeof schema.toJSONSchema === 'function' ? schema.toJSONSchema() : schema;
+    if (!isJsonObject(value)) {
+        throw new TypeError('Stagehand extract schema must resolve to a JSON object');
+    }
+    const { $schema, ...jsonSchema } = value;
+    void $schema;
+    return jsonSchema;
+}
+function isJsonObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/pagination.d.ts

@@ -0,0 +1,2 @@
+import type { V1ListEnvelope, V1PageQuery } from './types.js';
+export declare function iterateV1Pages<T, Q extends V1PageQuery>(initialQuery: Q, fetchPage: (query: Q) => Promise<V1ListEnvelope<T>>): AsyncGenerator<T, void, undefined>;

package/dist/pagination.js

@@ -0,0 +1,13 @@
+export async function* iterateV1Pages(initialQuery, fetchPage) {
+    let cursor = initialQuery.cursor;
+    for (;;) {
+        const page = await fetchPage({ ...initialQuery, cursor });
+        for (const item of page.data) {
+            yield item;
+        }
+        if (!page.nextCursor) {
+            return;
+        }
+        cursor = page.nextCursor;
+    }
+}

package/dist/runs.d.ts

@@ -0,0 +1,40 @@
+import type { V1HttpClient } from './http.js';
+import { V1RunFilesClient } from './files.js';
+import type { V1ListEnvelope, V1Run, V1RunCommand, V1RunCommandsListQuery, V1RunEvent, V1RunEventsListQuery, V1RunEventsWaitRequest, V1RunEventsWaitResponse, V1RunListQuery, V1RunLiveRequest, V1RunLiveResponse, V1RunRecordingRequest, V1RunRecordingResponse, V1RunUsage } from './types.js';
+export declare class V1RunEventsClient {
+    private readonly http;
+    private readonly runId;
+    constructor(http: V1HttpClient, runId: string);
+    list(query?: V1RunEventsListQuery): Promise<V1ListEnvelope<V1RunEvent>>;
+    iter(query?: V1RunEventsListQuery): AsyncGenerator<V1RunEvent, void, undefined>;
+    wait(request?: V1RunEventsWaitRequest): Promise<V1RunEventsWaitResponse>;
+    streamUrl(query?: Pick<V1RunEventsListQuery, 'type' | 'category' | 'connectionId'>): string;
+}
+export declare class V1RunCommandsClient {
+    private readonly http;
+    private readonly runId;
+    constructor(http: V1HttpClient, runId: string);
+    list(query?: V1RunCommandsListQuery): Promise<V1ListEnvelope<V1RunCommand>>;
+    iter(query?: V1RunCommandsListQuery): AsyncGenerator<V1RunCommand, void, undefined>;
+}
+export declare class V1RunResource {
+    private readonly http;
+    readonly data: V1Run;
+    readonly events: V1RunEventsClient;
+    readonly commands: V1RunCommandsClient;
+    readonly files: V1RunFilesClient;
+    constructor(http: V1HttpClient, data: V1Run);
+    get id(): string;
+    refresh(): Promise<V1RunResource>;
+    live(request?: V1RunLiveRequest): Promise<V1RunLiveResponse>;
+    recording(request?: V1RunRecordingRequest): Promise<V1RunRecordingResponse>;
+    usage(): Promise<V1RunUsage>;
+}
+export declare class V1RunsClient {
+    private readonly http;
+    constructor(http: V1HttpClient);
+    list(query?: V1RunListQuery): Promise<V1ListEnvelope<V1Run>>;
+    iter(query?: V1RunListQuery): AsyncGenerator<V1Run, void, undefined>;
+    get(id: string): Promise<V1RunResource>;
+    usage(id: string): Promise<V1RunUsage>;
+}