@bctrl/sdk 1.0.1

package/dist/ai-credentials/client.js

@@ -0,0 +1,70 @@
+import { fetchWithTimeout, parseErrorDetails, parseJsonResponse } from '../utils/http.js';
+import { SDK_VERSION } from '../version.js';
+function buildHeaders(apiKey, withJsonBody = false) {
+    const headers = {
+        'x-sdk-version': SDK_VERSION,
+        Authorization: `Bearer ${apiKey}`,
+    };
+    if (withJsonBody) {
+        headers['Content-Type'] = 'application/json';
+    }
+    return headers;
+}
+async function expectJson(response, context) {
+    if (!response.ok) {
+        const details = parseErrorDetails(await response.text());
+        throw new Error(`${context}: ${details.message}`);
+    }
+    return parseJsonResponse(response, context);
+}
+export class AiCredentialsClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+    }
+    async list() {
+        const response = await fetchWithTimeout(`${this.baseUrl}/ai-credentials`, {
+            headers: buildHeaders(this.apiKey),
+        });
+        const data = await expectJson(response, 'List AI credentials');
+        return data.credentials;
+    }
+    async create(request) {
+        const response = await fetchWithTimeout(`${this.baseUrl}/ai-credentials`, {
+            method: 'POST',
+            headers: buildHeaders(this.apiKey, true),
+            body: JSON.stringify(request),
+        });
+        return expectJson(response, 'Create AI credential');
+    }
+    async get(id) {
+        const response = await fetchWithTimeout(`${this.baseUrl}/ai-credentials/${encodeURIComponent(id)}`, {
+            headers: buildHeaders(this.apiKey),
+        });
+        return expectJson(response, 'Get AI credential');
+    }
+    async update(id, request) {
+        const response = await fetchWithTimeout(`${this.baseUrl}/ai-credentials/${encodeURIComponent(id)}`, {
+            method: 'PATCH',
+            headers: buildHeaders(this.apiKey, true),
+            body: JSON.stringify(request),
+        });
+        return expectJson(response, 'Update AI credential');
+    }
+    async delete(id) {
+        const response = await fetchWithTimeout(`${this.baseUrl}/ai-credentials/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+            headers: buildHeaders(this.apiKey),
+        });
+        await expectJson(response, 'Delete AI credential');
+    }
+    async test(id) {
+        const response = await fetchWithTimeout(`${this.baseUrl}/ai-credentials/${encodeURIComponent(id)}/test`, {
+            method: 'POST',
+            headers: buildHeaders(this.apiKey),
+        });
+        return expectJson(response, 'Test AI credential');
+    }
+}

package/dist/ai-credentials/index.d.ts

@@ -0,0 +1 @@
+export { AiCredentialsClient } from './client.js';

package/dist/ai-credentials/index.js

@@ -0,0 +1 @@
+export { AiCredentialsClient } from './client.js';

package/dist/base/event-binding.d.ts

@@ -0,0 +1,7 @@
+export interface RemoteListenerBinding {
+    onFirstListener(event: string): void;
+    onNoListeners(event: string): void;
+}
+export declare const REMOTE_LISTENER_BINDING_SYMBOL: unique symbol;
+export declare function getRemoteListenerBinding(target: unknown): RemoteListenerBinding | null;
+export declare function setRemoteListenerBinding(target: unknown, binding: RemoteListenerBinding | null): void;

package/dist/base/event-binding.js

@@ -0,0 +1,23 @@
+export const REMOTE_LISTENER_BINDING_SYMBOL = Symbol.for('bctrl.remoteListenerBinding');
+function isRemoteListenerBinding(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const onFirstListener = Reflect.get(value, 'onFirstListener');
+    const onNoListeners = Reflect.get(value, 'onNoListeners');
+    return typeof onFirstListener === 'function' && typeof onNoListeners === 'function';
+}
+export function getRemoteListenerBinding(target) {
+    if (!target || typeof target !== 'object')
+        return null;
+    const candidate = Reflect.get(target, REMOTE_LISTENER_BINDING_SYMBOL);
+    return isRemoteListenerBinding(candidate) ? candidate : null;
+}
+export function setRemoteListenerBinding(target, binding) {
+    if (!target || typeof target !== 'object')
+        return;
+    if (!binding) {
+        Reflect.deleteProperty(target, REMOTE_LISTENER_BINDING_SYMBOL);
+        return;
+    }
+    Reflect.set(target, REMOTE_LISTENER_BINDING_SYMBOL, binding);
+}

package/dist/base/types.d.ts

@@ -0,0 +1,109 @@
+export type { DriverType, RpcMessage as _RpcMessage } from '../contracts/runtime.js';
+type InternalBctrlEnvironment = 'production' | 'development';
+/**
+ * Profile selection options
+ */
+export interface ProfileOptions {
+    /** Use existing profile by ID */
+    id?: string;
+    /** Use existing profile by name */
+    name?: string;
+    /** Create new profile with this name */
+    createName?: string;
+}
+/**
+ * Connection options for connecting to bctrl
+ */
+export interface ConnectOptions {
+    /** Profile to use (by ID or name) */
+    profile?: ProfileOptions;
+    /** API key for authentication */
+    apiKey: string;
+    /**
+     * Target environment.
+     * Defaults to `production` (`https://api.bctrl.ai`).
+     * Use `development` for a local gateway on `http://localhost:8787`.
+     */
+    environment?: InternalBctrlEnvironment;
+    /**
+     * Gateway origin or API base URL.
+     * If you pass an origin, the SDK appends `/v1` automatically.
+     */
+    baseUrl?: string;
+    /** Browser options */
+    browserOptions?: {
+        /** Run browser in headless mode */
+        headless?: boolean;
+    };
+    /** Enable human-like mouse movement via CDP proxy (default: true) */
+    humanize?: boolean;
+    /** Mouse persona ID for humanization (0-124) */
+    humanizePersonaId?: number;
+}
+/**
+ * Locator step for remote locator chains
+ */
+export interface LocatorStep {
+    /** Locator method (e.g., 'locator', 'getByRole', 'getByText') */
+    method: string;
+    /** Arguments for the locator method */
+    args: unknown[];
+}
+import type { DriverType, RpcTarget } from '../contracts/runtime.js';
+/**
+ * SDK RPC message for sending commands to control-plane
+ */
+export interface RpcMessageSdk {
+    /** Driver type */
+    driver: DriverType;
+    /** Target object (browser, context, page, locator) */
+    target: RpcTarget;
+    /** Method to call on the target */
+    method: string;
+    /** Arguments for the method */
+    args: unknown[];
+    /** Page ID for page-specific operations */
+    pageId?: string;
+    /** Context ID for context-specific operations */
+    contextId?: string;
+    /** Locator chain for locator operations */
+    locatorChain?: LocatorStep[];
+}
+/**
+ * Session information returned from control-plane
+ */
+export interface SessionInfo {
+    /** Unique session ID */
+    id: string;
+    /** Default browser context ID (if applicable) */
+    defaultContextId?: string;
+    /** Default page ID (if applicable) */
+    defaultPageId?: string;
+}
+/**
+ * Select options
+ */
+export interface SelectOption {
+    value?: string;
+    label?: string;
+    index?: number;
+}
+/**
+ * Keyboard press options
+ */
+export interface PressOptions {
+    delay?: number;
+}
+/**
+ * Mouse click options
+ */
+export interface MouseClickOptions {
+    button?: 'left' | 'right' | 'middle';
+    clickCount?: number;
+}
+/**
+ * Evaluate options
+ */
+export interface EvaluateOptions {
+    timeout?: number;
+}

package/dist/base/types.js

@@ -0,0 +1,4 @@
+// ============================================================================
+// Base Types - Common types for SDK redesign
+// ============================================================================
+export {};

package/dist/bctrl.d.ts

@@ -0,0 +1,37 @@
+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;
+}
+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 {};

package/dist/bctrl.js

@@ -0,0 +1,77 @@
+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();
+        }
+    }
+    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,
+    });
+}

package/dist/browser-extensions/client.d.ts

@@ -0,0 +1,15 @@
+import type { BrowserExtensionDeleteResponse, BrowserExtensionImportRequest, ExtensionMetadata } from '../contracts/public-api.js';
+export interface BrowserExtensionUploadRequest {
+    file: Buffer | Uint8Array | Blob;
+    filename: string;
+}
+export declare class BrowserExtensionsClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    list(): Promise<ExtensionMetadata[]>;
+    upload(request: BrowserExtensionUploadRequest): Promise<ExtensionMetadata>;
+    importFromUrl(request: BrowserExtensionImportRequest): Promise<ExtensionMetadata>;
+    get(id: string): Promise<ExtensionMetadata>;
+    delete(id: string): Promise<BrowserExtensionDeleteResponse>;
+}

package/dist/browser-extensions/client.js

@@ -0,0 +1,72 @@
+import { fetchWithTimeout, parseErrorDetails, parseJsonResponse } from '../utils/http.js';
+import { SDK_VERSION } from '../version.js';
+function buildHeaders(apiKey) {
+    return {
+        'x-sdk-version': SDK_VERSION,
+        Authorization: `Bearer ${apiKey}`,
+    };
+}
+function buildJsonHeaders(apiKey) {
+    return {
+        ...buildHeaders(apiKey),
+        'Content-Type': 'application/json',
+    };
+}
+async function expectJson(response, context) {
+    if (!response.ok) {
+        const details = parseErrorDetails(await response.text());
+        throw new Error(`${context}: ${details.message}`);
+    }
+    return parseJsonResponse(response, context);
+}
+function toBlob(data) {
+    if (data instanceof Blob)
+        return data;
+    return new Blob([new Uint8Array(data)]);
+}
+export class BrowserExtensionsClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+    }
+    async list() {
+        const response = await fetchWithTimeout(`${this.baseUrl}/browser-extensions`, {
+            headers: buildHeaders(this.apiKey),
+        });
+        const data = await expectJson(response, 'List browser extensions');
+        return data.extensions;
+    }
+    async upload(request) {
+        const formData = new FormData();
+        formData.append('file', toBlob(request.file), request.filename);
+        const response = await fetchWithTimeout(`${this.baseUrl}/browser-extensions/upload`, {
+            method: 'POST',
+            headers: buildHeaders(this.apiKey),
+            body: formData,
+        });
+        return expectJson(response, 'Upload browser extension');
+    }
+    async importFromUrl(request) {
+        const response = await fetchWithTimeout(`${this.baseUrl}/browser-extensions/import-url`, {
+            method: 'POST',
+            headers: buildJsonHeaders(this.apiKey),
+            body: JSON.stringify(request),
+        });
+        return expectJson(response, 'Import browser extension');
+    }
+    async get(id) {
+        const response = await fetchWithTimeout(`${this.baseUrl}/browser-extensions/${encodeURIComponent(id)}`, {
+            headers: buildHeaders(this.apiKey),
+        });
+        return expectJson(response, 'Get browser extension');
+    }
+    async delete(id) {
+        const response = await fetchWithTimeout(`${this.baseUrl}/browser-extensions/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+            headers: buildHeaders(this.apiKey),
+        });
+        return expectJson(response, 'Delete browser extension');
+    }
+}

package/dist/browser-extensions/index.d.ts

@@ -0,0 +1,2 @@
+export { BrowserExtensionsClient } from './client.js';
+export type { BrowserExtensionUploadRequest } from './client.js';

package/dist/browser-extensions/index.js

@@ -0,0 +1 @@
+export { BrowserExtensionsClient } from './client.js';

package/dist/browser-profiles/client.d.ts

@@ -0,0 +1,11 @@
+import type { BrowserProfile, BrowserProfileCreateRequest, BrowserProfileDeleteResponse, BrowserProfileDetail, BrowserProfileUpdateRequest } from '../contracts/public-api.js';
+export declare class BrowserProfilesClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    list(): Promise<BrowserProfile[]>;
+    create(request: BrowserProfileCreateRequest): Promise<BrowserProfileDetail>;
+    get(id: string): Promise<BrowserProfileDetail>;
+    update(id: string, request: BrowserProfileUpdateRequest): Promise<BrowserProfileDetail>;
+    delete(id: string): Promise<BrowserProfileDeleteResponse>;
+}

package/dist/browser-profiles/client.js

@@ -0,0 +1,63 @@
+import { fetchWithTimeout, parseErrorDetails, parseJsonResponse } from '../utils/http.js';
+import { SDK_VERSION } from '../version.js';
+function buildHeaders(apiKey, withJsonBody = false) {
+    const headers = {
+        'x-sdk-version': SDK_VERSION,
+        Authorization: `Bearer ${apiKey}`,
+    };
+    if (withJsonBody) {
+        headers['Content-Type'] = 'application/json';
+    }
+    return headers;
+}
+async function expectJson(response, context) {
+    if (!response.ok) {
+        const details = parseErrorDetails(await response.text());
+        throw new Error(`${context}: ${details.message}`);
+    }
+    return parseJsonResponse(response, context);
+}
+export class BrowserProfilesClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+    }
+    async list() {
+        const response = await fetchWithTimeout(`${this.baseUrl}/browser-profiles`, {
+            headers: buildHeaders(this.apiKey),
+        });
+        const data = await expectJson(response, 'List browser profiles');
+        return data.profiles;
+    }
+    async create(request) {
+        const response = await fetchWithTimeout(`${this.baseUrl}/browser-profiles`, {
+            method: 'POST',
+            headers: buildHeaders(this.apiKey, true),
+            body: JSON.stringify(request),
+        });
+        return expectJson(response, 'Create browser profile');
+    }
+    async get(id) {
+        const response = await fetchWithTimeout(`${this.baseUrl}/browser-profiles/${encodeURIComponent(id)}`, {
+            headers: buildHeaders(this.apiKey),
+        });
+        return expectJson(response, 'Get browser profile');
+    }
+    async update(id, request) {
+        const response = await fetchWithTimeout(`${this.baseUrl}/browser-profiles/${encodeURIComponent(id)}`, {
+            method: 'PATCH',
+            headers: buildHeaders(this.apiKey, true),
+            body: JSON.stringify(request),
+        });
+        return expectJson(response, 'Update browser profile');
+    }
+    async delete(id) {
+        const response = await fetchWithTimeout(`${this.baseUrl}/browser-profiles/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+            headers: buildHeaders(this.apiKey),
+        });
+        return expectJson(response, 'Delete browser profile');
+    }
+}

package/dist/browser-profiles/index.d.ts

@@ -0,0 +1 @@
+export { BrowserProfilesClient } from './client.js';

package/dist/browser-profiles/index.js

@@ -0,0 +1 @@
+export { BrowserProfilesClient } from './client.js';

package/dist/captcha/index.d.ts

@@ -0,0 +1 @@
+export { CaptchaNamespace } from './namespace.js';

package/dist/captcha/index.js

@@ -0,0 +1 @@
+export { CaptchaNamespace } from './namespace.js';

package/dist/captcha/namespace.d.ts

@@ -0,0 +1,34 @@
+/**
+ * CaptchaNamespace — SDK methods for captcha detection and solving
+ *
+ * Provides `detect()` and `solve()` methods that send RPC calls
+ * to the browser-host via the page target.
+ */
+import type { CaptchaDetectArgs, CaptchaDetectResult, CaptchaSolveArgs, CaptchaSolveResult } from '../contracts/captcha.js';
+import type { RpcSender } from '../internal/transport.js';
+export declare class CaptchaNamespace {
+    private sendRpc;
+    private getActivePageId;
+    constructor(sendRpc: RpcSender, getActivePageId: () => string | undefined);
+    /**
+     * Detect captchas on the current page.
+     *
+     * @example
+     * const result = await session.captcha.detect();
+     * if (result.found) {
+     *   console.log('Found captchas:', result.captchas);
+     * }
+     */
+    detect(options?: CaptchaDetectArgs): Promise<CaptchaDetectResult>;
+    /**
+     * Detect and solve a captcha on the current page.
+     * Detects the captcha type, sends to solver backend, and injects the token.
+     *
+     * @example
+     * const result = await session.captcha.solve();
+     * if (result.success) {
+     *   console.log(`Solved ${result.type} in ${result.duration}ms`);
+     * }
+     */
+    solve(options?: CaptchaSolveArgs): Promise<CaptchaSolveResult>;
+}

package/dist/captcha/namespace.js

@@ -0,0 +1,41 @@
+/**
+ * CaptchaNamespace — SDK methods for captcha detection and solving
+ *
+ * Provides `detect()` and `solve()` methods that send RPC calls
+ * to the browser-host via the page target.
+ */
+export class CaptchaNamespace {
+    sendRpc;
+    getActivePageId;
+    constructor(sendRpc, getActivePageId) {
+        this.sendRpc = sendRpc;
+        this.getActivePageId = getActivePageId;
+    }
+    /**
+     * Detect captchas on the current page.
+     *
+     * @example
+     * const result = await session.captcha.detect();
+     * if (result.found) {
+     *   console.log('Found captchas:', result.captchas);
+     * }
+     */
+    async detect(options) {
+        const pageId = this.getActivePageId();
+        return this.sendRpc('page', 'captcha.detect', [options ?? {}], { pageId });
+    }
+    /**
+     * Detect and solve a captcha on the current page.
+     * Detects the captcha type, sends to solver backend, and injects the token.
+     *
+     * @example
+     * const result = await session.captcha.solve();
+     * if (result.success) {
+     *   console.log(`Solved ${result.type} in ${result.duration}ms`);
+     * }
+     */
+    async solve(options) {
+        const pageId = this.getActivePageId();
+        return this.sendRpc('page', 'captcha.solve', [options ?? {}], { pageId });
+    }
+}

package/dist/client/index.d.ts

@@ -0,0 +1 @@
+export * from './rpc.js';

package/dist/client/index.js

@@ -0,0 +1 @@
+export * from './rpc.js';