@bctrl/sdk 1.0.1

package/dist/client/rpc.d.ts

@@ -0,0 +1,83 @@
+import type { RpcTarget } from '../internal/transport.js';
+import type { BrowserDriver } from '../contracts/runtime.js';
+import type { VaultSessionPolicy } from '../contracts/vault.js';
+import type { SessionStoragePolicy } from '../contracts/storage.js';
+/**
+ * RPC call to control-plane
+ * @param endpoint - Full URL of the endpoint
+ * @param body - Request body
+ * @param timeout - Optional timeout in milliseconds (default: DEFAULT_TIMEOUT_MS)
+ */
+export declare function rpc<T>(endpoint: string, body: Record<string, unknown>, timeout?: number): Promise<T>;
+/**
+ * Start an ephemeral browser session through the API gateway (no driver connected).
+ * @param baseUrl - Versioned API base URL of the gateway (e.g., 'http://localhost:8787/v1')
+ * @param options - Session start options
+ */
+export declare function startSession(baseUrl: string, options?: {
+    apiKey?: string;
+    humanize?: boolean;
+    humanizePersonaId?: number;
+    proxy?: {
+        type: 'http' | 'socks5';
+        host: string;
+        port: number;
+        username?: string;
+        password?: string;
+    } | null;
+    storage?: SessionStoragePolicy;
+    solveCaptchas?: boolean;
+    vault?: VaultSessionPolicy;
+}): Promise<{
+    id: string;
+    status: 'active' | 'stopped';
+    storageWorkspace?: string;
+}>;
+/**
+ * Connect a driver to an existing started session on the control-plane.
+ */
+export declare function connectSessionDriver(baseUrl: string, sessionId: string, driver: BrowserDriver, apiKey?: string): Promise<{
+    id: string;
+    currentDriver: BrowserDriver;
+    defaultContextId?: string;
+    defaultPageId?: string;
+    storageWorkspace?: string;
+}>;
+/**
+ * Stop a session on the control-plane
+ * @param baseUrl - Versioned API base URL of the control-plane
+ * @param sessionId - Session ID to stop
+ * @param apiKey - Optional API key
+ */
+export declare function stopSession(baseUrl: string, sessionId: string, apiKey?: string): Promise<void>;
+/**
+ * Send RPC/EXECUTE command through the canonical automation endpoint.
+ * @param baseUrl - Versioned API base URL of the control-plane
+ * @param sessionId - Session ID
+ * @param command - RPC or EXECUTE command
+ * @param timeout - Optional timeout in milliseconds
+ */
+type SendCommandInput = {
+    type: 'RPC';
+    correlationId?: string;
+    target: RpcTarget;
+    method: string;
+    args: unknown[];
+    contextId?: string;
+    pageId?: string;
+    handleId?: string;
+} | {
+    type: 'EXECUTE';
+    correlationId?: string;
+    code: string;
+    args?: Record<string, unknown>;
+    pageId?: string;
+    options?: {
+        timeoutMs?: number;
+        logs?: 'off' | 'capture';
+        scriptId?: string;
+        scriptName?: string;
+    };
+};
+export declare function sendCommand<T>(baseUrl: string, sessionId: string, command: SendCommandInput, apiKey?: string, timeout?: number): Promise<T>;
+export {};

package/dist/client/rpc.js

@@ -0,0 +1,354 @@
+// ============================================================================
+// RPC Client - HTTP calls to control-plane
+// ============================================================================
+import { parseJsonResponse, fetchWithTimeout, DEFAULT_TIMEOUT_MS, LONG_TIMEOUT_MS, } from '../utils/http.js';
+import { fromErrorResponse, AuthenticationError, SessionError, TimeoutError, } from '../errors.js';
+import * as telemetry from '../telemetry.js';
+import { SDK_VERSION } from '../version.js';
+import { CONTEXT_REF_TARGETS, HANDLE_TARGETS, PAGE_REF_TARGETS, } from '../internal/rpc-targets.js';
+/**
+ * Map an HTTP status code + response text to a typed BctrlError.
+ */
+function httpStatusToError(status, text, fallbackMessage) {
+    if (status === 401 || status === 403)
+        return new AuthenticationError(`Authentication failed: ${text}`);
+    if (status === 404)
+        return new SessionError(`Not found: ${text}`, 'NOT_FOUND');
+    if (status === 504)
+        return new TimeoutError(`Gateway timeout: ${text}`);
+    if (status === 503)
+        return new SessionError(`Service unavailable: ${text}`, 'CONNECTION_ERROR');
+    return fromErrorResponse(fallbackMessage ?? `HTTP ${status}: ${text}`);
+}
+/**
+ * Extract timeout (ms) from an RPC method options argument if present.
+ * Many automation APIs use the last arg as an options object with `timeout`.
+ */
+function getRpcOptionsTimeoutMs(args) {
+    if (!Array.isArray(args) || args.length === 0)
+        return undefined;
+    const lastArg = args[args.length - 1];
+    if (!lastArg || typeof lastArg !== 'object' || Array.isArray(lastArg))
+        return undefined;
+    const timeoutRaw = lastArg.timeout;
+    if (typeof timeoutRaw !== 'number' || !Number.isFinite(timeoutRaw) || timeoutRaw <= 0) {
+        return undefined;
+    }
+    return Math.floor(timeoutRaw);
+}
+/**
+ * Methods that are expected to wait on browser state and may run longer than 30s.
+ */
+function isLongRunningRpcMethod(method) {
+    return (method.startsWith('wait') ||
+        method === 'goto' ||
+        method === 'reload' ||
+        method === 'setContent');
+}
+const AGENT_RPC_TIMEOUT_MS = 5 * 60 * 1000;
+function isLongRunningAgentRpc(target, method) {
+    if (target === 'browserUse') {
+        return method === 'agent.execute' || method === 'codeAgent.execute';
+    }
+    if (target === 'stagehand') {
+        return method === 'agent.execute';
+    }
+    return false;
+}
+function trimTrailingUndefined(args) {
+    if (!Array.isArray(args))
+        return args;
+    let end = args.length;
+    while (end > 0 && args[end - 1] === undefined) {
+        end -= 1;
+    }
+    return end === args.length ? args : args.slice(0, end);
+}
+function parseAutomationEnvelope(text) {
+    if (!text)
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function buildAutomationError(error, fallbackMessage) {
+    const message = error?.message || fallbackMessage;
+    const hint = error?.hint;
+    const diagnostic = error?.diagnostic;
+    const context = {};
+    if (hint)
+        context.hint = hint;
+    if (diagnostic)
+        context.diagnostic = diagnostic;
+    return fromErrorResponse(hint ? `${message} (${hint})` : message, error?.code, Object.keys(context).length > 0 ? context : undefined);
+}
+/**
+ * RPC call to control-plane
+ * @param endpoint - Full URL of the endpoint
+ * @param body - Request body
+ * @param timeout - Optional timeout in milliseconds (default: DEFAULT_TIMEOUT_MS)
+ */
+export async function rpc(endpoint, body, timeout) {
+    const response = await fetchWithTimeout(endpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'x-sdk-version': SDK_VERSION,
+        },
+        body: JSON.stringify(body),
+    }, timeout ?? DEFAULT_TIMEOUT_MS);
+    // Read request ID from response for error context
+    const requestId = response.headers.get('x-request-id') ?? undefined;
+    if (!response.ok) {
+        const text = await response.text();
+        const err = httpStatusToError(response.status, text);
+        telemetry.captureError(err, {
+            endpoint,
+            method: 'POST',
+            statusCode: response.status,
+            errorCode: err.code,
+            requestId,
+        });
+        throw err;
+    }
+    const data = await parseJsonResponse(response, `RPC ${endpoint}`);
+    if (data.status === 'error') {
+        const err = fromErrorResponse(data.error || 'Unknown error', data.errorCode, data.errorContext);
+        telemetry.captureError(err, {
+            endpoint,
+            method: 'POST',
+            statusCode: response.status,
+            errorCode: data.errorCode,
+            requestId,
+        });
+        throw err;
+    }
+    return data.result;
+}
+/**
+ * Start an ephemeral browser session through the API gateway (no driver connected).
+ * @param baseUrl - Versioned API base URL of the gateway (e.g., 'http://localhost:8787/v1')
+ * @param options - Session start options
+ */
+export async function startSession(baseUrl, options = {}) {
+    const headers = {
+        'Content-Type': 'application/json',
+        'x-sdk-version': SDK_VERSION,
+    };
+    if (options.apiKey) {
+        headers['Authorization'] = `Bearer ${options.apiKey}`;
+    }
+    const response = await fetchWithTimeout(`${baseUrl}/sessions`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+            humanize: options.humanize,
+            humanizePersonaId: options.humanizePersonaId,
+            proxy: options.proxy,
+            storage: options.storage,
+            solveCaptchas: options.solveCaptchas,
+            vault: options.vault,
+        }),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        const err = httpStatusToError(response.status, text, `Failed to start session: ${text}`);
+        telemetry.captureError(err, {
+            endpoint: `${baseUrl}/sessions`,
+            method: 'POST',
+            statusCode: response.status,
+            errorCode: err.code,
+            requestId,
+        });
+        throw err;
+    }
+    const data = await parseJsonResponse(response, 'Start session');
+    return {
+        id: data.id,
+        status: data.status,
+        storageWorkspace: data.storageWorkspace,
+    };
+}
+/**
+ * Connect a driver to an existing started session on the control-plane.
+ */
+export async function connectSessionDriver(baseUrl, sessionId, driver, apiKey) {
+    const headers = {
+        'Content-Type': 'application/json',
+        'x-sdk-version': SDK_VERSION,
+    };
+    if (apiKey) {
+        headers['Authorization'] = `Bearer ${apiKey}`;
+    }
+    const response = await fetchWithTimeout(`${baseUrl}/sessions/${sessionId}/connect`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ driver }),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        const err = httpStatusToError(response.status, text, `Failed to connect session driver: ${text}`);
+        telemetry.captureError(err, {
+            endpoint: `${baseUrl}/sessions/${sessionId}/connect`,
+            method: 'POST',
+            statusCode: response.status,
+            errorCode: err.code,
+            requestId,
+        });
+        throw err;
+    }
+    return parseJsonResponse(response, 'Connect session driver');
+}
+/**
+ * Stop a session on the control-plane
+ * @param baseUrl - Versioned API base URL of the control-plane
+ * @param sessionId - Session ID to stop
+ * @param apiKey - Optional API key
+ */
+export async function stopSession(baseUrl, sessionId, apiKey) {
+    const headers = {
+        'Content-Type': 'application/json',
+        'x-sdk-version': SDK_VERSION,
+    };
+    if (apiKey) {
+        headers['Authorization'] = `Bearer ${apiKey}`;
+    }
+    const response = await fetchWithTimeout(`${baseUrl}/sessions/${sessionId}/stop`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({}),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        const err = httpStatusToError(response.status, text, `Failed to stop session: ${text}`);
+        telemetry.captureError(err, {
+            endpoint: `${baseUrl}/sessions/${sessionId}/stop`,
+            method: 'POST',
+            statusCode: response.status,
+            errorCode: err.code,
+            requestId,
+        });
+        throw err;
+    }
+}
+async function sendCommandInternal(baseUrl, sessionId, command, apiKey, timeout) {
+    const executeTimeoutMs = command.type === 'EXECUTE' &&
+        typeof command.options?.timeoutMs === 'number' &&
+        Number.isFinite(command.options.timeoutMs) &&
+        command.options.timeoutMs > 0
+        ? Math.floor(command.options.timeoutMs)
+        : undefined;
+    const rpcOptionsTimeoutMs = command.type === 'RPC'
+        ? getRpcOptionsTimeoutMs(command.args)
+        : undefined;
+    const rpcTimeoutHint = command.type === 'RPC'
+        ? rpcOptionsTimeoutMs !== undefined
+            ? Math.max(DEFAULT_TIMEOUT_MS, rpcOptionsTimeoutMs + 5000)
+            : isLongRunningRpcMethod(command.method)
+                ? LONG_TIMEOUT_MS
+                : undefined
+        : undefined;
+    const aiRpcTimeoutHint = command.type === 'RPC' &&
+        'target' in command &&
+        (command.target === 'stagehand' || command.target === 'browserUse') &&
+        rpcOptionsTimeoutMs !== undefined
+        ? Math.max(isLongRunningAgentRpc(command.target, command.method) ? AGENT_RPC_TIMEOUT_MS : LONG_TIMEOUT_MS, rpcOptionsTimeoutMs + 5000)
+        : undefined;
+    // Use longer timeout for potentially slow AI operations (stagehand, browserUse, execute)
+    const defaultTimeout = command.type === 'EXECUTE' ||
+        ('target' in command && (command.target === 'stagehand' || command.target === 'browserUse'))
+        ? command.type === 'EXECUTE' && executeTimeoutMs !== undefined
+            ? Math.max(LONG_TIMEOUT_MS, executeTimeoutMs + 5000)
+            : (aiRpcTimeoutHint ??
+                ('target' in command && isLongRunningAgentRpc(command.target, command.method)
+                    ? AGENT_RPC_TIMEOUT_MS
+                    : LONG_TIMEOUT_MS))
+        : (rpcTimeoutHint ?? DEFAULT_TIMEOUT_MS);
+    let call;
+    let ref;
+    let args;
+    let options;
+    if (command.type === 'RPC') {
+        call = `${command.target}.${command.method}`;
+        args = trimTrailingUndefined(command.args);
+        if (HANDLE_TARGETS.has(command.target)) {
+            ref = command.handleId;
+        }
+        else if (CONTEXT_REF_TARGETS.has(command.target)) {
+            ref = command.contextId;
+        }
+        else if (PAGE_REF_TARGETS.has(command.target)) {
+            ref = command.pageId;
+        }
+        if (rpcOptionsTimeoutMs !== undefined) {
+            options = { timeoutMs: rpcOptionsTimeoutMs };
+        }
+    }
+    else {
+        call = 'execute';
+        args = [command.code];
+        if (command.args !== undefined) {
+            args.push(command.args);
+        }
+        ref = command.pageId;
+        options = command.options;
+    }
+    const endpoint = `${baseUrl}/sessions/${encodeURIComponent(sessionId)}/automation`;
+    const response = await fetchWithTimeout(endpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'x-sdk-version': SDK_VERSION,
+            ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        },
+        body: JSON.stringify({
+            call,
+            ...(ref ? { ref } : {}),
+            ...(args ? { args } : {}),
+            ...(options ? { options } : {}),
+        }),
+    }, timeout ?? defaultTimeout);
+    const requestId = response.headers.get('x-request-id') ?? undefined;
+    if (!response.ok) {
+        const text = await response.text();
+        const parsed = parseAutomationEnvelope(text);
+        const err = parsed && parsed.ok === false
+            ? buildAutomationError(parsed.error, text || `Automation ${call} failed`)
+            : httpStatusToError(response.status, text);
+        const telemetryErrorCode = parsed?.error?.code ||
+            err.code;
+        telemetry.captureError(err, {
+            endpoint,
+            method: 'POST',
+            statusCode: response.status,
+            errorCode: telemetryErrorCode,
+            commandType: command.type,
+            requestId,
+        });
+        throw err;
+    }
+    const data = await parseJsonResponse(response, `Automation ${call}`);
+    if (data.ok !== true) {
+        const err = buildAutomationError(data.error, 'Unknown error');
+        telemetry.captureError(err, {
+            endpoint,
+            method: 'POST',
+            statusCode: response.status,
+            errorCode: data.error?.code,
+            commandType: command.type,
+            requestId,
+        });
+        throw err;
+    }
+    return data.result;
+}
+export async function sendCommand(baseUrl, sessionId, command, apiKey, timeout) {
+    return sendCommandInternal(baseUrl, sessionId, command, apiKey, timeout);
+}

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+export declare const BCTRL_PRODUCTION_ORIGIN = "https://api.bctrl.ai";
+export declare const BCTRL_DEVELOPMENT_ORIGIN = "http://localhost:8787";
+export declare function resolveProductionApiBaseUrl(): string;
+export declare function resolveInternalApiBaseUrl(originOrApiBase?: string): string;
+export declare function resolveApiKey(apiKey: string): string;

package/dist/config.js

@@ -0,0 +1,28 @@
+import { PUBLIC_API_PREFIX } from './contracts/version.js';
+import { stripTrailingSlash } from './utils/url.js';
+export const BCTRL_PRODUCTION_ORIGIN = 'https://api.bctrl.ai';
+export const BCTRL_DEVELOPMENT_ORIGIN = 'http://localhost:8787';
+function toApiBaseUrl(originOrApiBase) {
+    const normalized = stripTrailingSlash(originOrApiBase);
+    return normalized.endsWith(PUBLIC_API_PREFIX)
+        ? normalized
+        : `${normalized}${PUBLIC_API_PREFIX}`;
+}
+export function resolveProductionApiBaseUrl() {
+    return toApiBaseUrl(BCTRL_PRODUCTION_ORIGIN);
+}
+export function resolveInternalApiBaseUrl(originOrApiBase) {
+    if (originOrApiBase === undefined) {
+        return toApiBaseUrl(BCTRL_DEVELOPMENT_ORIGIN);
+    }
+    if (typeof originOrApiBase !== 'string' || originOrApiBase.trim() === '') {
+        throw new Error('Internal Bctrl apiOrigin must be a non-empty string when provided');
+    }
+    return toApiBaseUrl(originOrApiBase.trim());
+}
+export function resolveApiKey(apiKey) {
+    if (typeof apiKey !== 'string' || apiKey.trim() === '') {
+        throw new Error('Bctrl apiKey is required');
+    }
+    return apiKey.trim();
+}

package/dist/constants/browser.d.ts

@@ -0,0 +1,2 @@
+import type { BrowserDriver } from '../contracts/runtime.js';
+export declare const DEFAULT_BROWSER_DRIVER: BrowserDriver;

package/dist/constants/browser.js

@@ -0,0 +1 @@
+export const DEFAULT_BROWSER_DRIVER = 'playwright';

package/dist/contracts/agent-tools.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+export declare const AgentStorageToolConfigSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    prefix: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodString>>>;
+    inputFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type AgentStorageToolConfig = z.infer<typeof AgentStorageToolConfigSchema>;
+export declare const AgentVaultToolConfigSchema: z.ZodObject<{
+    toolPrefix: z.ZodOptional<z.ZodString>;
+    defaultListFilter: z.ZodOptional<z.ZodObject<{
+        prefix: z.ZodOptional<z.ZodString>;
+        origin: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    allowRawReads: z.ZodOptional<z.ZodBoolean>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type AgentVaultToolConfig = z.infer<typeof AgentVaultToolConfigSchema>;
+export declare const AgentCaptchaToolConfigSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    pageId: z.ZodOptional<z.ZodUUID>;
+}, z.core.$strict>;
+export type AgentCaptchaToolConfig = z.infer<typeof AgentCaptchaToolConfigSchema>;
+export declare const AgentInvocationToolsSchema: z.ZodObject<{
+    storage: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        prefix: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodString>>>;
+        inputFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    vault: z.ZodOptional<z.ZodObject<{
+        toolPrefix: z.ZodOptional<z.ZodString>;
+        defaultListFilter: z.ZodOptional<z.ZodObject<{
+            prefix: z.ZodOptional<z.ZodString>;
+            origin: z.ZodOptional<z.ZodString>;
+            limit: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        allowRawReads: z.ZodOptional<z.ZodBoolean>;
+        enabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    captcha: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        pageId: z.ZodOptional<z.ZodUUID>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AgentInvocationTools = z.infer<typeof AgentInvocationToolsSchema>;

package/dist/contracts/agent-tools.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { VaultAgentAdapterConfigSchema } from './vault.js';
+const OptionalTrimmedStringSchema = z.preprocess((value) => {
+    if (typeof value !== 'string')
+        return value;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}, z.string().optional());
+export const AgentStorageToolConfigSchema = z
+    .object({
+    enabled: z.boolean().optional(),
+    prefix: OptionalTrimmedStringSchema.optional(),
+    inputFiles: z.array(z.string().min(1)).optional(),
+})
+    .strict();
+export const AgentVaultToolConfigSchema = VaultAgentAdapterConfigSchema.extend({
+    enabled: z.boolean().optional(),
+}).strict();
+export const AgentCaptchaToolConfigSchema = z
+    .object({
+    enabled: z.boolean().optional(),
+    pageId: z.uuid().optional(),
+})
+    .strict();
+export const AgentInvocationToolsSchema = z
+    .object({
+    storage: AgentStorageToolConfigSchema.optional(),
+    vault: AgentVaultToolConfigSchema.optional(),
+    captcha: AgentCaptchaToolConfigSchema.optional(),
+})
+    .strict();