@bctrl/sdk

import { ... } from '@bctrl/sdk';

class AuthenticationError extends BctrlError

new (message: string, context?: Record<string, unknown>)

class AutomationError extends BctrlError

new (message: string, code?: string, context?: Record<string, unknown>)

class Bctrl

new (options: BctrlOptions)

browser(name: string): BrowserHandle

defineScript<TParams extends ZodTypeAny, TResult, TScriptPage extends BaseScriptPage = BaseScriptPage>(input: DefineScriptInput<TParams, TResult, TScriptPage>): ScriptDefinition<TParams, TResult, TScriptPage>

getHosts(): Promise<string[]>

health(): Promise<{ status: string; connectedHosts: number }>

storage(workspaceName: string): StorageClient

class BctrlError extends Error

new (message: string, code: string, context?: Record<string, unknown>)

toJSON(): Record<string, unknown>

class ExtensionsClient

new (baseUrl: string, apiKey?: string)

delete(id: string): Promise<void>

get(id: string): Promise<ExtensionMetadata | null>

install(browserName: string, extensionIds: string | string[]): Promise<void>

installed(browserName: string): Promise<ExtensionMetadata[]>

list(): Promise<ExtensionMetadata[]>

uninstall(browserName: string, extensionId: string): Promise<void>

update(id: string, opts: { file: Buffer; filename: string }): Promise<ExtensionMetadata>

upload(opts: {
    file?: Buffer;
    filename?: string;
    url?: string;
  }): Promise<ExtensionMetadata>

class AutomationError extends BctrlError

new (message: string, code?: string, context?: Record<string, unknown>)

class SessionError extends BctrlError

new (message: string, code?: string, context?: Record<string, unknown>)

class StorageClient

new (baseUrl: string, workspace: string, apiKey?: string, sessionId?: string)

browse(options?: StorageBrowseOptions): Promise<StorageBrowseResult>

delete(filePath: string): Promise<void>

deleteAll(): Promise<number>

deleteObject(id: string): Promise<void>

downloadObject(id: string): Promise<Buffer>

forWorkspace(workspace: string): StorageClient

get(filePath: string): Promise<Buffer>

getDownloadsZip(): Promise<Buffer>

getDownloadUrl(filePath: string): Promise<string>

getObjectDownloadUrl(id: string): Promise<string>

listObjects(options?: ListObjectsOptions): Promise<StorageObject[]>

read(filePath: string, maxBytes?: number): Promise<StorageReadResult>

upload(filePath: string, data: Buffer | Uint8Array | Blob, filename?: string): Promise<UploadResult>

uploadObject(data: Buffer | Uint8Array | Blob, options?: UploadObjectOptions): Promise<UploadObjectResult>

class TimeoutError extends BctrlError

new (message: string, context?: Record<string, unknown>)

class VaultClient

new (baseUrl: string, apiKey?: string, sessionId?: string)

delete(key: string): Promise<void>

get(key: string): Promise<VaultCredential | null>

list(input?: string | VaultListKeyOptions | VaultListMetaOptions): Promise<string[] | VaultCredentialMeta[]>

set(key: string, credential: VaultCredentialInput): Promise<void>

totp(key: string): Promise<string>

connectSessionDriver(baseUrl: string, sessionId: string, driver: BrowserDriver, apiKey?: string): Promise<{
  id: string;
  hostId: string;
  currentDriver: BrowserDriver;
  defaultContextId?: string;
  defaultPageId?: string;
  storageWorkspace?: string;
}>

defineScript<TParams extends ZodTypeAny, TResult, TScriptPage extends BaseScriptPage = BaseScriptPage>(input: DefineScriptInput<TParams, TResult, TScriptPage>): ScriptDefinition<TParams, TResult, TScriptPage>

fromErrorResponse(message: string, code?: string, context?: Record<string, unknown>): BctrlError

getAutomationDiagnostic(error: unknown): AutomationDiagnostic | undefined

getAutomationHint(error: unknown): string | undefined

isAuthenticationError(error: unknown): error is AuthenticationError

isAutomationError(error: unknown): error is AutomationError

isBctrlError(error: unknown): error is BctrlError

isSessionError(error: unknown): error is SessionError

isTimeoutError(error: unknown): error is TimeoutError

rpc<T>(endpoint: string, body: Record<string, unknown>, timeout?: number): Promise<T>

sendCommand<T>(baseUrl: string, _hostId: string, sessionId: string, command: SendCommandInput, timeout?: number): Promise<T>

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;
  hostId: string;
  status: 'active' | 'stopped';
  storageWorkspace?: string;
}>

stopSession(baseUrl: string, sessionId: string, apiKey?: string): Promise<void>

export interface BctrlOptions {
  /** API key for authentication */
  apiKey: string;
  /**
   * Target environment.
   * Defaults to `production` (`https://api.bctrl.ai`).
   * Use `development` for a local control plane on `http://localhost:3000`.
   */
  environment?: BctrlEnvironment;
  /**
   * Control plane origin or API base URL.
   * If you pass an origin, the SDK appends `/v1` automatically.
   */
  baseUrl?: string;
  /** Enable anonymous telemetry (error tracking). Set to false to opt out. @default true */
  telemetry?: boolean;
}

export interface BrowserConfigInfo {
  name: string;
  humanize: boolean;
  hasProxy: boolean;
  updatedAt: string | null;
}

export interface BrowserConnectApi {
  (): Promise<PlaywrightSession>;
  playwright(): Promise<PlaywrightSession>;
  puppeteer(): Promise<PuppeteerSession>;
  stagehand(): Promise<StagehandSession>;
  selenium(): Promise<SeleniumSession>;
}

export interface BrowserCreateResult {
  /** Browser name */
  name: string;
  /** Creation status */
  status: 'created';
  /** Default humanize setting */
  humanize: boolean;
  /** Whether proxy is configured */
  hasProxy: boolean;
}

export interface BrowserHandle {
  name: string;
  create(options?: CreateOptions): Promise<BrowserCreateResult>;
  connect: BrowserConnectApi;
  start(
    options?: StartOptions
  ): Promise<{ name: string; status: string; sessionId?: string; waited?: boolean }>;
  stop(): Promise<{ name: string; status: string }>;
  status(): Promise<BrowserInfo>;
  configure(options: ConfigureOptions): Promise<BrowserConfigInfo>;
  upgrade(): Promise<BrowserUpgradeInfo | null>;
  delete(): Promise<{ name: string; status: string }>;
}

export interface BrowserInfo {
  /** Browser name */
  name: string;
  /** Current status */
  status: 'running' | 'stopped';
  /** Currently connected driver (if running) */
  currentDriver: string | null;
  /** Default humanize setting */
  humanize: boolean;
  /** Whether proxy is configured */
  hasProxy: boolean;
  /** Creation timestamp */
  createdAt: string;
  /** Last used timestamp */
  lastUsedAt: string | null;
}

export interface BrowserUpgradeInfo {
  fingerprint: {
    browser: {
      product: string;
      major: number;
      version: string;
    };
  } | null;
}

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 control plane on `http://localhost:3000`.
   */
  environment?: BctrlEnvironment;
  /**
   * Control plane 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;
}

export interface CreateOptions {
  /**
   * Default proxy configuration for this named browser profile.
   *
   * Notes:
   * - Applied when the underlying Kameleo profile is (lazily) provisioned.
   * - Can be temporarily overridden per session via bctrl.browser(name).start({ proxy }).
   * - Can be updated while stopped via the control-plane profile update API.
   */
  proxy?: ProxyConfig;

  /**
   * Default humanize setting for this browser.
   * Can be overridden when calling start().
   * @default true
   */
  humanize?: boolean;
}

export interface CreateSessionOptions {
  /**
   * Enable/disable humanization for this session (defaults to backend default).
   */
  humanize?: boolean;

  /**
   * Mouse persona ID for humanization (0-124).
   */
  humanizePersonaId?: number;

  /**
   * Temporary proxy for this ephemeral session. Use null to force direct connection.
   */
  proxy?: ProxyConfig | null;

  /**
   * Session-level storage access policy for this ephemeral session.
   */
  storage?: SessionStoragePolicy;

  /**
   * Enable automatic captcha detection/solving.
   */
  solveCaptchas?: boolean;

  /**
   * Session-scoped vault access policy.
   */
  vault?: VaultSessionPolicy;
}

export interface EvaluateOptions {
  timeout?: number;
}

export interface ExecuteOptions<TScriptPage extends BaseScriptPage = ScriptPage> {
  /** Function, defineScript(), or serialized function string to execute */
  fn: ScriptFn<any, TScriptPage> | ScriptDefinition<ZodTypeAny, any, TScriptPage> | string;
  /** Named browser to connect to. The browser must already be running; if omitted, an ephemeral session is used. */
  browser?: string;
  /** Driver type (defaults to 'playwright') */
  driver?: DriverType;
  /** Parameters passed as ctx.params (and injected as aliases) inside the script */
  params?: Record<string, unknown>;
  /** Execution timeout in milliseconds (max 10 minutes) */
  timeoutMs?: number;
  /** Target page ID (defaults to active/default page) */
  pageId?: string;
  /** Script log capture mode */
  logs?: ExecuteLogsMode;
  /** Optional callback replayed for each captured log entry after completion */
  onLog?: ScriptExecutionOptions['onLog'];
}

export interface ListObjectsOptions {
  workspace?: string;
  sessionId?: string;
  source?: string;
  driver?: string;
  target?: string;
  pathPrefix?: string;
  limit?: number;
  offset?: number;
}

export interface ListObjectsResult {
  objects: StorageObject[];
}

export interface LocatorStep {
  /** Locator method (e.g., 'locator', 'getByRole', 'getByText') */
  method: string;
  /** Arguments for the locator method */
  args: unknown[];
}

export interface MouseClickOptions {
  button?: 'left' | 'right' | 'middle';
  clickCount?: number;
}

export interface PresignedUrlResult {
  url: string;
  key?: string;
  expiresIn: number;
}

export interface PressOptions {
  delay?: number;
}

export interface ProfileApi {
  create(options?: ProfileCreateOptions): Promise<Profile>;
  list(options?: ProfileListOptions): Promise<ProfileListResult>;
  get(profileId: string): Promise<Profile>;
  start(profileId: string, options?: ProfileStartRequest): Promise<ProfileStartResult>;
  connect(
    profileId: string,
    request?: Partial<ProfileConnectRequest>
  ): Promise<ProfileConnectResult>;
  stop(profileId: string): Promise<ProfileStopResponse>;
  status(profileId: string): Promise<ProfileLifecycleStatus>;
  delete(profileId: string): Promise<void>;
}

export interface ProfileConnectResult {
  profileId: string;
  sessionId: string;
  hostId: string;
  driver: BrowserDriver;
  previousDriver: string | null;
  reused: boolean;
  driverChanged: boolean;
  storageWorkspace?: string;
  defaultContextId?: string;
  defaultPageId?: string;
}

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;
}

export interface ProfileStartResult {
  profileId: string;
  kind: 'browser';
  status: 'started' | 'already_running';
  sessionId: string;
  waited: boolean;
}

export interface ProxyConfig {
  /** Proxy type */
  type: 'http' | 'socks5';
  /** Proxy host */
  host: string;
  /** Proxy port */
  port: number;
  /** Proxy username (optional) */
  username?: string;
  /** Proxy password (optional) */
  password?: string;
}

export interface RpcMessageSdk {
  /** Driver type */
  driver: DriverType;
  /** Target object (browser, context, page, locator) */
  target: string;
  /** 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[];
}

export interface SelectOption {
  value?: string;
  label?: string;
  index?: number;
}

export interface SessionApi {
  (options?: CreateSessionOptions): Promise<PlaywrightSession>;
  playwright(options?: CreateSessionOptions): Promise<PlaywrightSession>;
  puppeteer(options?: CreateSessionOptions): Promise<PuppeteerSession>;
  stagehand(options?: CreateSessionOptions): Promise<StagehandSession>;
  selenium(options?: CreateSessionOptions): Promise<SeleniumSession>;
}

export interface SessionInfo {
  /** Unique session ID */
  id: string;
  /** Host ID where session is running */
  hostId: string;
  /** Default browser context ID (if applicable) */
  defaultContextId?: string;
  /** Default page ID (if applicable) */
  defaultPageId?: string;
}

export interface SessionsApi {
  start(options?: SessionStartOptions): Promise<StartedSessionData>;
  connect(
    sessionId: string,
    request?: Partial<SessionConnectRequest>
  ): Promise<SessionConnectResponse>;
  stop(sessionId: string): Promise<void>;
  list(): Promise<Array<{ id: string; hostId: string; status: string }>>;
  get(
    sessionId: string
  ): Promise<{ id: string; hostId: string; status: string; storageWorkspace?: string }>;
}

export interface StartedSessionData {
  id: string;
  hostId: string;
  status?: 'active' | 'stopped';
  storageWorkspace?: string;
}

export interface StartOptions {
  /**
   * Override the browser's default humanize setting.
   * If not provided, uses the browser's default from create().
   */
  humanize?: boolean;

  /**
   * Temporary proxy override for this start only.
   * Requires the browser to be stopped (will error if already running).
   * Use null to force a direct connection for this one session.
   */
  proxy?: ProxyConfig | null;

  /**
   * Session-level storage access policy for this started browser session.
   * If omitted, the platform default workspace is used and access is unrestricted.
   */
  storage?: SessionStoragePolicy;
}

export interface StorageBrowseOptions {
  prefix?: string;
  cursor?: string;
  limit?: number;
}

export interface StorageObject {
  id: string;
  workspace: string;
  sessionId: string | null;
  source: string;
  driver: string | null;
  target: string | null;
  logicalPath: string;
  filename: string;
  contentType: string;
  sizeBytes: number;
  createdAt: string | null;
  expiresAt: string | null;
  metadata: Record<string, unknown> | null;
}

export interface UploadObjectOptions {
  workspace?: string;
  path?: string;
  source?: string;
  sessionId?: string;
  driver?: string;
  target?: string;
  filename?: string;
}

export interface UploadObjectResult {
  id: string;
  workspace: string;
  logicalPath: string;
  objectKey: string;
  filename: string;
  sizeBytes: number;
  contentType: string;
  expiresAt: string | null;
}

export interface UploadResult {
  success: boolean;
  key: string;
  filename: string;
}

export type BctrlEnvironment = 'production' | 'development';

export type StorageBrowseFile = StorageBrowseResult['files'][number];

export type StorageBrowseResult = StorageBrowseResponse;

export type StorageReadResult = StorageReadResponse;