@bctrl/sdk 1.0.8 → 1.0.10

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 BCTRL
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

package/README.md

@@ -1,72 +1,116 @@
-# @bctrl/sdk
-
-TypeScript SDK for BCTRL v1 spaces, browser runtimes, invocations, runs, and files.
-
-## Install
-
-```bash
-npm install @bctrl/sdk
-```
-
-Node 18+ is required.
-
-## Quick start
-
-```ts
-import { Bctrl } from '@bctrl/sdk';
-import { z } from 'zod';
-
-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);
-
-const invocation = await bctrl.runtimes.invocations.createAndWait(
-  started.runtimeId,
-  {
-    action: 'extract',
-    instruction: 'Extract the page title.',
-    schema: z.object({
-      title: z.string(),
-    }),
-  },
-  { timeoutMs: 60_000 }
-);
-
-console.log(invocation.status, invocation.output);
-
-await bctrl.runtimes.stop(started.runtimeId);
-```
-
-The public SDK targets `https://api.bctrl.ai/v1`. For local development, pass a
-local origin or v1 base URL:
-
-```ts
-const bctrl = new Bctrl({
-  apiKey: process.env.BCTRL_API_KEY!,
-  baseUrl: 'http://localhost:8787',
-});
-```
-
-`baseUrl` may include or omit `/v1`; the client normalizes either form.
-
-## Entry points
-
-- `@bctrl/sdk`: v1 client, resources, errors, and public types
-
-## Documentation
-
-- SDK reference: https://platform.bctrl.ai/api-reference/sdk/overview
-- Product site: https://bctrl.ai
-
-## Telemetry
-
-The published SDK does not include vendor-owned telemetry or usage analytics.
-
-If you want observability around SDK calls, instrument your application directly with your own logging or error tracking.
+# @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
+
+```bash
+npm install @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,
+});
+
+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(),
+    }),
+  },
+  { 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();
+```
+
+You can also pass configuration explicitly:
+
+```ts
+const bctrl = new Bctrl({
+  apiKey: 'bctrl_...',
+  timeoutMs: 30_000,
+  maxRetries: 2,
+});
+```
+
+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';
+
+try {
+  await bctrl.runtimes.get('<runtime-id>');
+} catch (error) {
+  if (error instanceof BctrlApiError) {
+    console.error(error.status, error.code, error.requestId);
+  }
+}
+```
+
+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.

package/dist/account.d.ts

@@ -1,4 +1,5 @@
 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';
 export declare class V1AuthClient {
     private readonly http;
@@ -37,6 +38,7 @@ export declare class V1UsageClient {
 }
 export declare class V1AccountClient {
     readonly apiKeys: V1ApiKeysClient;
+    readonly notificationRecipients: V1NotificationRecipientsClient;
     readonly subaccounts: V1SubaccountsClient;
     readonly usage: V1UsageClient;
     constructor(http: V1HttpClient);

package/dist/account.js

@@ -1,3 +1,4 @@
+import { V1NotificationRecipientsClient } from './notificationRecipients.js';
 import { iterateV1Pages } from './pagination.js';
 export class V1AuthClient {
     http;
@@ -90,10 +91,12 @@ export class V1UsageClient {
 }
 export class V1AccountClient {
     apiKeys;
+    notificationRecipients;
     subaccounts;
     usage;
     constructor(http) {
         this.apiKeys = new V1ApiKeysClient(http);
+        this.notificationRecipients = new V1NotificationRecipientsClient(http);
         this.subaccounts = new V1SubaccountsClient(http);
         this.usage = new V1UsageClient(http);
     }

package/dist/bctrl.d.ts

@@ -4,6 +4,7 @@ import { V1BrowserExtensionsClient } from './browserExtensions.js';
 import { V1FilesClient } from './files.js';
 import { V1HelpClient } from './help.js';
 import { type V1ClientOptions } from './http.js';
+import { V1NotificationRecipientsClient } from './notificationRecipients.js';
 import { V1ProxiesClient } from './proxies.js';
 import { V1RunsClient } from './runs.js';
 import { V1RuntimesClient } from './runtimes.js';
@@ -14,6 +15,7 @@ import { V1ToolsetsClient } from './toolsets.js';
 import { V1VaultClient } from './vault.js';
 export type BctrlV1Options = V1ClientOptions;
 export declare class BctrlV1 {
+    private readonly options;
     private readonly http;
     private _spaces;
     private _runtimes;
@@ -32,8 +34,10 @@ export declare class BctrlV1 {
     private _auth;
     private _subaccounts;
     private _usage;
+    private _notificationRecipients;
     static isControllerBusy(error: unknown): boolean;
     constructor(options?: BctrlV1Options);
+    withSubaccount(subaccountId: string): BctrlV1;
     get spaces(): V1SpacesClient;
     get runtimes(): V1RuntimesClient;
     get runs(): V1RunsClient;
@@ -51,5 +55,6 @@ export declare class BctrlV1 {
     get auth(): V1AuthClient;
     get subaccounts(): V1SubaccountsClient;
     get usage(): V1UsageClient;
+    get notificationRecipients(): V1NotificationRecipientsClient;
 }
 export { BctrlV1 as Bctrl };

package/dist/bctrl.js

@@ -5,6 +5,7 @@ import { isControllerBusy } from './errors.js';
 import { V1FilesClient } from './files.js';
 import { V1HelpClient } from './help.js';
 import { V1HttpClient } from './http.js';
+import { V1NotificationRecipientsClient } from './notificationRecipients.js';
 import { V1ProxiesClient } from './proxies.js';
 import { V1RunsClient } from './runs.js';
 import { V1RuntimesClient } from './runtimes.js';
@@ -14,6 +15,7 @@ import { V1ToolsClient } from './tools.js';
 import { V1ToolsetsClient } from './toolsets.js';
 import { V1VaultClient } from './vault.js';
 export class BctrlV1 {
+    options;
     http;
     _spaces = null;
     _runtimes = null;
@@ -32,11 +34,16 @@ export class BctrlV1 {
     _auth = null;
     _subaccounts = null;
     _usage = null;
+    _notificationRecipients = null;
     static isControllerBusy(error) {
         return isControllerBusy(error);
     }
     constructor(options = {}) {
-        this.http = new V1HttpClient(options);
+        this.options = { ...options };
+        this.http = new V1HttpClient(this.options);
+    }
+    withSubaccount(subaccountId) {
+        return new BctrlV1({ ...this.options, subaccountId });
     }
     get spaces() {
         this._spaces ??= new V1SpacesClient(this.http);
@@ -106,5 +113,9 @@ export class BctrlV1 {
         this._usage ??= new V1UsageClient(this.http);
         return this._usage;
     }
+    get notificationRecipients() {
+        this._notificationRecipients ??= new V1NotificationRecipientsClient(this.http);
+        return this._notificationRecipients;
+    }
 }
 export { BctrlV1 as Bctrl };

package/dist/browserExtensionTypes.d.ts

@@ -8,8 +8,6 @@ export interface V1BrowserExtensionUploadRequest {
     file: Blob;
     /** Optional display name. Defaults to manifest.name. */
     name?: string;
-    /** Parent/org keys may create inside a child subaccount. */
-    subaccountId?: string;
 }
 export type V1BrowserExtensionImportRequest = OpenApiSchemas['BrowserExtensionImportRequest'];
 export type V1BrowserExtensionUpdateRequest = OpenApiSchemas['BrowserExtensionUpdateRequest'];

package/dist/browserExtensions.js

@@ -25,9 +25,6 @@ export class V1BrowserExtensionsClient {
         if (request.name) {
             form.set('name', request.name);
         }
-        if (request.subaccountId) {
-            form.set('subaccountId', request.subaccountId);
-        }
         return this.http.request('/browser-extensions/upload', {
             method: 'POST',
             body: form,