@bctrl/sdk 1.0.10 → 1.0.11

package/README.md

@@ -1,116 +1,43 @@
-# @bctrl/sdk
-
-TypeScript and JavaScript SDK for BCTRL cloud browser automation. Create browser runtimes, start live sessions, run hosted browser agents, inspect runs, and manage platform resources from Node.js.
-
-## Install
+# BCTRL JavaScript SDK
 
 ```bash
-npm install @bctrl/sdk
+pnpm add @bctrl/sdk
 ```
 
-Requires Node.js 22.14 or newer.
-
-## Quick Start
-
 ```ts
 import { Bctrl } from '@bctrl/sdk';
 
-const bctrl = new Bctrl({
-  apiKey: process.env.BCTRL_API_KEY!,
-});
-
-const runtime = await bctrl.runtimes.create({
-  type: 'browser',
-  name: 'browser-task',
-});
-
-const started = await bctrl.runtimes.start(runtime.id);
-console.log(started.runId, started.connectUrl);
-
-await bctrl.runtimes.targets.create(started.runtimeId, {
-  uri: 'https://example.com',
-  activate: true,
-});
+const bctrl = new Bctrl({ apiKey: process.env.BCTRL_API_KEY });
+const started = await bctrl.runtimes.start('rt_...');
 
-await bctrl.runtimes.stop(started.runtimeId);
-```
-
-## Hosted Invocations
-
-Use invocations when you want BCTRL to drive the browser for you.
-
-```ts
-import { Bctrl } from '@bctrl/sdk';
-import { z } from 'zod';
-
-const bctrl = new Bctrl();
-
-const invocation = await bctrl.runtimes.invocations.createAndWait(
-  '<runtime-id>',
-  {
-    action: 'extract',
-    instruction: 'Extract the product name and price.',
-    schema: z.object({
-      name: z.string(),
-      price: z.string(),
-    }),
+const result = await bctrl.tools.call('stagehand.extract', {
+  runtimeId: started.runtimeId,
+  instruction: 'Extract the products',
+  schema: {
+    type: 'object',
+    properties: { products: { type: 'array' } },
   },
-  { timeoutSeconds: 60 }
-);
-
-console.log(invocation.status, invocation.output);
-```
-
-The SDK accepts Zod schemas or plain JSON Schema for structured extraction. On the wire, they are sent as `outputSchema`.
-
-## Configuration
-
-The client reads `BCTRL_API_KEY` by default:
+});
 
-```ts
-const bctrl = new Bctrl();
+const call = await bctrl.tools.start('captcha.solve', { runtimeId: started.runtimeId });
+const solved = await bctrl.toolCalls.result(call.id, { waitSeconds: 60 });
 ```
 
-You can also pass configuration explicitly:
+Agents are persistent conversations attached to an active runtime:
 
 ```ts
-const bctrl = new Bctrl({
-  apiKey: 'bctrl_...',
-  timeoutMs: 30_000,
-  maxRetries: 2,
+const conversation = await bctrl.conversations.create({
+  agent: 'browser-use',
+  runtimeId: started.runtimeId,
 });
-```
-
-For subaccount-scoped calls:
 
-```ts
-const scoped = bctrl.withSubaccount('<subaccount-id>');
-```
-
-## Errors
-
-API failures throw typed errors with status, code, request id, and response body context:
-
-```ts
-import { BctrlApiError } from '@bctrl/sdk';
+await bctrl.conversations.messages.create(conversation.id, {
+  text: 'Find the lowest refundable price',
+});
 
-try {
-  await bctrl.runtimes.get('<runtime-id>');
-} catch (error) {
-  if (error instanceof BctrlApiError) {
-    console.error(error.status, error.code, error.requestId);
-  }
-}
+const streamUrl = bctrl.conversations.events.streamUrl(conversation.id);
 ```
 
-The client retries retryable GET requests by default. Mutating requests are retried only when you provide an idempotency key.
-
-## Documentation
-
-- SDK guide: https://platform.bctrl.ai/sdk
-- API reference: https://platform.bctrl.ai/api-reference
-- Product: https://bctrl.ai
-
-## Telemetry
-
-The SDK does not include vendor-owned telemetry or usage analytics. Instrument your application directly if you want request logging or tracing.
+Every automation path writes into the runtime's Run. Inspect structured spans and
+events with `bctrl.runs.trace`, `bctrl.runs.events`, or the unified Run stream URL.
+Create a View when a browser-safe, expiring embed URL is needed.

package/dist/account.d.ts

@@ -1,6 +1,6 @@
 import type { V1HttpClient } from './http.js';
 import { V1NotificationRecipientsClient } from './notificationRecipients.js';
-import type { V1AccountUsage, V1ApiKey, V1ApiKeyCreateRequest, V1ApiKeyCreateResponse, V1ApiKeyDeleteResponse, V1ApiKeyListQuery, V1AuthWhoamiResponse, V1ListEnvelope, V1Subaccount, V1SubaccountArchiveResponse, V1SubaccountCreateRequest, V1SubaccountGetQuery, V1SubaccountListQuery, V1SubaccountUpdateRequest, V1SubaccountUsage, V1SubaccountUsageListQuery } from './types.js';
+import type { V1Account, V1AccountPatchRequest, V1AccountUpdateQuery, V1AccountUsage, V1ApiKey, V1ApiKeyCreateRequest, V1ApiKeyCreateResponse, V1ApiKeyDeleteResponse, V1ApiKeyListQuery, V1AuthWhoamiResponse, V1ListEnvelope, V1Subaccount, V1SubaccountArchiveResponse, V1SubaccountCreateRequest, V1SubaccountGetQuery, V1SubaccountListQuery, V1SubaccountUpdateRequest, V1SubaccountUsage, V1SubaccountUsageListQuery } from './types.js';
 export declare class V1AuthClient {
     private readonly http;
     constructor(http: V1HttpClient);
@@ -37,9 +37,12 @@ export declare class V1UsageClient {
     get(): Promise<V1AccountUsage>;
 }
 export declare class V1AccountClient {
+    private readonly http;
     readonly apiKeys: V1ApiKeysClient;
     readonly notificationRecipients: V1NotificationRecipientsClient;
     readonly subaccounts: V1SubaccountsClient;
     readonly usage: V1UsageClient;
     constructor(http: V1HttpClient);
+    get(): Promise<V1Account>;
+    update(request: V1AccountPatchRequest, query?: V1AccountUpdateQuery): Promise<V1Account>;
 }

package/dist/account.js

@@ -90,14 +90,26 @@ export class V1UsageClient {
     }
 }
 export class V1AccountClient {
+    http;
     apiKeys;
     notificationRecipients;
     subaccounts;
     usage;
     constructor(http) {
+        this.http = http;
         this.apiKeys = new V1ApiKeysClient(http);
         this.notificationRecipients = new V1NotificationRecipientsClient(http);
         this.subaccounts = new V1SubaccountsClient(http);
         this.usage = new V1UsageClient(http);
     }
+    get() {
+        return this.http.request('/account');
+    }
+    update(request, query = {}) {
+        return this.http.request('/account', {
+            method: 'PATCH',
+            query,
+            body: request,
+        });
+    }
 }

package/dist/aiTypes.d.ts

@@ -12,8 +12,5 @@ export type V1AiCredentialCreateRequest = OpenApiSchemas['AiCredentialCreateRequ
 export type V1AiCredentialUpdateRequest = OpenApiSchemas['AiCredentialUpdateRequest'];
 export type V1AiCredentialDeleteResponse = OpenApiSchemas['AiCredentialDeleteResponse'];
 export type V1AiCredentialTestResponse = OpenApiSchemas['AiCredentialTestResponse'];
-export type V1AiModelSelectionAuth = OpenApiSchemas['AiModelSelectionAuth'];
-export type V1AiModelSelectionObject = OpenApiSchemas['AiModelSelection'];
-export type V1AiModelSelection = string | V1AiModelSelectionObject;
 export type V1AiStoredModelSelectionAuth = OpenApiSchemas['AiStoredModelSelectionAuth'];
 export type V1AiStoredModelSelection = string | OpenApiSchemas['AiStoredModelSelection'];

package/dist/bctrl.d.ts

@@ -1,6 +1,7 @@
 import { V1AccountClient, V1ApiKeysClient, V1AuthClient, V1SubaccountsClient, V1UsageClient } from './account.js';
 import { V1AiClient } from './ai.js';
 import { V1BrowserExtensionsClient } from './browserExtensions.js';
+import { V1ConversationsClient } from './conversations.js';
 import { V1FilesClient } from './files.js';
 import { V1HelpClient } from './help.js';
 import { type V1ClientOptions } from './http.js';
@@ -12,7 +13,8 @@ import { V1SpacesClient } from './spaces.js';
 import { V1ToolCallsClient } from './toolCalls.js';
 import { V1ToolsClient } from './tools.js';
 import { V1ToolsetsClient } from './toolsets.js';
-import { V1VaultClient } from './vault.js';
+import { V1ViewsClient } from './views.js';
+import { V1WebhooksClient } from './webhooks.js';
 export type BctrlV1Options = V1ClientOptions;
 export declare class BctrlV1 {
     private readonly options;
@@ -20,12 +22,12 @@ export declare class BctrlV1 {
     private _spaces;
     private _runtimes;
     private _runs;
+    private _conversations;
     private _files;
     private _help;
     private _tools;
     private _toolsets;
     private _toolCalls;
-    private _vault;
     private _proxies;
     private _browserExtensions;
     private _ai;
@@ -35,18 +37,20 @@ export declare class BctrlV1 {
     private _subaccounts;
     private _usage;
     private _notificationRecipients;
+    private _views;
+    private _webhooks;
     static isControllerBusy(error: unknown): boolean;
     constructor(options?: BctrlV1Options);
     withSubaccount(subaccountId: string): BctrlV1;
     get spaces(): V1SpacesClient;
     get runtimes(): V1RuntimesClient;
     get runs(): V1RunsClient;
+    get conversations(): V1ConversationsClient;
     get files(): V1FilesClient;
     get help(): V1HelpClient;
     get tools(): V1ToolsClient;
     get toolsets(): V1ToolsetsClient;
     get toolCalls(): V1ToolCallsClient;
-    get vault(): V1VaultClient;
     get proxies(): V1ProxiesClient;
     get browserExtensions(): V1BrowserExtensionsClient;
     get ai(): V1AiClient;
@@ -56,5 +60,7 @@ export declare class BctrlV1 {
     get subaccounts(): V1SubaccountsClient;
     get usage(): V1UsageClient;
     get notificationRecipients(): V1NotificationRecipientsClient;
+    get views(): V1ViewsClient;
+    get webhooks(): V1WebhooksClient;
 }
 export { BctrlV1 as Bctrl };

package/dist/bctrl.js

@@ -1,6 +1,7 @@
 import { V1AccountClient, V1ApiKeysClient, V1AuthClient, V1SubaccountsClient, V1UsageClient, } from './account.js';
 import { V1AiClient } from './ai.js';
 import { V1BrowserExtensionsClient } from './browserExtensions.js';
+import { V1ConversationsClient } from './conversations.js';
 import { isControllerBusy } from './errors.js';
 import { V1FilesClient } from './files.js';
 import { V1HelpClient } from './help.js';
@@ -13,19 +14,20 @@ import { V1SpacesClient } from './spaces.js';
 import { V1ToolCallsClient } from './toolCalls.js';
 import { V1ToolsClient } from './tools.js';
 import { V1ToolsetsClient } from './toolsets.js';
-import { V1VaultClient } from './vault.js';
+import { V1ViewsClient } from './views.js';
+import { V1WebhooksClient } from './webhooks.js';
 export class BctrlV1 {
     options;
     http;
     _spaces = null;
     _runtimes = null;
     _runs = null;
+    _conversations = null;
     _files = null;
     _help = null;
     _tools = null;
     _toolsets = null;
     _toolCalls = null;
-    _vault = null;
     _proxies = null;
     _browserExtensions = null;
     _ai = null;
@@ -35,6 +37,8 @@ export class BctrlV1 {
     _subaccounts = null;
     _usage = null;
     _notificationRecipients = null;
+    _views = null;
+    _webhooks = null;
     static isControllerBusy(error) {
         return isControllerBusy(error);
     }
@@ -57,6 +61,10 @@ export class BctrlV1 {
         this._runs ??= new V1RunsClient(this.http);
         return this._runs;
     }
+    get conversations() {
+        this._conversations ??= new V1ConversationsClient(this.http);
+        return this._conversations;
+    }
     get files() {
         this._files ??= new V1FilesClient(this.http);
         return this._files;
@@ -77,10 +85,6 @@ export class BctrlV1 {
         this._toolCalls ??= new V1ToolCallsClient(this.http);
         return this._toolCalls;
     }
-    get vault() {
-        this._vault ??= new V1VaultClient(this.http);
-        return this._vault;
-    }
     get proxies() {
         this._proxies ??= new V1ProxiesClient(this.http);
         return this._proxies;
@@ -117,5 +121,13 @@ export class BctrlV1 {
         this._notificationRecipients ??= new V1NotificationRecipientsClient(this.http);
         return this._notificationRecipients;
     }
+    get views() {
+        this._views ??= new V1ViewsClient(this.http);
+        return this._views;
+    }
+    get webhooks() {
+        this._webhooks ??= new V1WebhooksClient(this.http);
+        return this._webhooks;
+    }
 }
 export { BctrlV1 as Bctrl };

package/dist/browserExtensionTypes.d.ts

@@ -2,13 +2,13 @@ import type { OpenApiQuery, OpenApiSchemas } from './openapi.js';
 export type V1BrowserExtensionFormat = OpenApiSchemas['BrowserExtension']['format'];
 export type V1BrowserExtensionSource = 'upload' | 'url';
 export type V1BrowserExtension = OpenApiSchemas['BrowserExtension'];
-export type V1BrowserExtensionListQuery = OpenApiQuery<'browser-extensions.list'>;
+export type V1BrowserExtensionListQuery = OpenApiQuery<'browser.extensions.list'>;
 export interface V1BrowserExtensionUploadRequest {
     /** Packed Chromium extension package. Only .crx is supported today. */
     file: Blob;
     /** Optional display name. Defaults to manifest.name. */
     name?: string;
 }
-export type V1BrowserExtensionImportRequest = OpenApiSchemas['BrowserExtensionImportRequest'];
+export type V1BrowserExtensionImportRequest = OpenApiSchemas['BrowserExtensionCreateRequest'];
 export type V1BrowserExtensionUpdateRequest = OpenApiSchemas['BrowserExtensionUpdateRequest'];
 export type V1BrowserExtensionDeleteResponse = OpenApiSchemas['BrowserExtensionDeleteResponse'];

package/dist/browserExtensions.js

@@ -9,7 +9,7 @@ export class V1BrowserExtensionsClient {
         this.http = http;
     }
     list(query = {}) {
-        return this.http.request('/browser-extensions', {
+        return this.http.request('/browser/extensions', {
             query,
         });
     }
@@ -17,7 +17,7 @@ export class V1BrowserExtensionsClient {
         return iterateV1Pages(query, (pageQuery) => this.list(pageQuery));
     }
     get(extensionId) {
-        return this.http.request(`/browser-extensions/${encodeURIComponent(extensionId)}`);
+        return this.http.request(`/browser/extensions/${encodeURIComponent(extensionId)}`);
     }
     upload(request) {
         const form = new FormData();
@@ -25,25 +25,25 @@ export class V1BrowserExtensionsClient {
         if (request.name) {
             form.set('name', request.name);
         }
-        return this.http.request('/browser-extensions/upload', {
+        return this.http.request('/browser/extensions', {
             method: 'POST',
             body: form,
         });
     }
     import(request) {
-        return this.http.request('/browser-extensions/import', {
+        return this.http.request('/browser/extensions', {
             method: 'POST',
             body: request,
         });
     }
     update(extensionId, request) {
-        return this.http.request(`/browser-extensions/${encodeURIComponent(extensionId)}`, {
+        return this.http.request(`/browser/extensions/${encodeURIComponent(extensionId)}`, {
             method: 'PATCH',
             body: request,
         });
     }
     delete(extensionId) {
-        return this.http.request(`/browser-extensions/${encodeURIComponent(extensionId)}`, {
+        return this.http.request(`/browser/extensions/${encodeURIComponent(extensionId)}`, {
             method: 'DELETE',
         });
     }

package/dist/conversations.d.ts

@@ -0,0 +1,27 @@
+import { type V1HttpClient, type V1IdempotencyOptions } from './http.js';
+import type { V1Conversation, V1ConversationCancelResponse, V1ConversationCreateRequest, V1ConversationDetail, V1ConversationListQuery, V1ConversationMessageCreateRequest, V1ConversationStreamQuery, V1ConversationStreamEvent, V1ConversationUpdateRequest, V1ConversationTurn, V1ListEnvelope } from './types.js';
+export declare class V1ConversationsClient {
+    private readonly http;
+    readonly messages: V1ConversationMessagesClient;
+    readonly events: V1ConversationEventsClient;
+    constructor(http: V1HttpClient);
+    list(query?: V1ConversationListQuery): Promise<V1ListEnvelope<V1Conversation>>;
+    iter(query?: V1ConversationListQuery): AsyncGenerator<V1Conversation, void, undefined>;
+    create(request: V1ConversationCreateRequest): Promise<V1Conversation>;
+    get(conversationId: string): Promise<V1ConversationDetail>;
+    update(conversationId: string, request: V1ConversationUpdateRequest): Promise<V1Conversation>;
+    cancel(conversationId: string): Promise<V1ConversationCancelResponse>;
+}
+export declare class V1ConversationMessagesClient {
+    private readonly http;
+    constructor(http: V1HttpClient);
+    create(conversationId: string, request: V1ConversationMessageCreateRequest, options?: V1IdempotencyOptions): Promise<V1ConversationTurn>;
+}
+export declare class V1ConversationEventsClient {
+    private readonly http;
+    constructor(http: V1HttpClient);
+    streamUrl(conversationId: string, query?: V1ConversationStreamQuery): string;
+    stream(conversationId: string, query?: V1ConversationStreamQuery, options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<V1ConversationStreamEvent, void, undefined>;
+}

package/dist/conversations.js

@@ -0,0 +1,63 @@
+import { v1IdempotencyHeaders } from './http.js';
+import { iterateV1Pages } from './pagination.js';
+export class V1ConversationsClient {
+    http;
+    messages;
+    events;
+    constructor(http) {
+        this.http = http;
+        this.messages = new V1ConversationMessagesClient(http);
+        this.events = new V1ConversationEventsClient(http);
+    }
+    list(query = {}) {
+        return this.http.request('/conversations', { query });
+    }
+    iter(query = {}) {
+        return iterateV1Pages(query, (pageQuery) => this.list(pageQuery));
+    }
+    create(request) {
+        return this.http.request('/conversations', { method: 'POST', body: request });
+    }
+    get(conversationId) {
+        return this.http.request(`/conversations/${encodeURIComponent(conversationId)}`);
+    }
+    update(conversationId, request) {
+        return this.http.request(`/conversations/${encodeURIComponent(conversationId)}`, {
+            method: 'PATCH',
+            body: request,
+        });
+    }
+    cancel(conversationId) {
+        return this.http.request(`/conversations/${encodeURIComponent(conversationId)}/cancel`, {
+            method: 'POST',
+        });
+    }
+}
+export class V1ConversationMessagesClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    create(conversationId, request, options) {
+        return this.http.request(`/conversations/${encodeURIComponent(conversationId)}/messages`, {
+            method: 'POST',
+            body: request,
+            headers: v1IdempotencyHeaders(options),
+        });
+    }
+}
+export class V1ConversationEventsClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    streamUrl(conversationId, query = {}) {
+        const url = new URL(`${this.http.baseUrl}/conversations/${encodeURIComponent(conversationId)}/stream`);
+        if (query.after !== undefined)
+            url.searchParams.set('after', query.after);
+        return url.toString();
+    }
+    stream(conversationId, query = {}, options = {}) {
+        return this.http.streamSse(`/conversations/${encodeURIComponent(conversationId)}/stream`, { query, signal: options.signal });
+    }
+}