@bctrl/sdk 1.0.4 → 1.0.6

package/README.md

@@ -1,72 +1,72 @@
-# @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';
-
-const bctrl = new Bctrl({
-  apiKey: process.env.BCTRL_API_KEY!,
-});
-
-const space = await bctrl.spaces.create({
-  name: 'my-task',
-  region: 'us-east-1',
-});
-
-const createdRuntime = await space.runtimes.create({
-  type: 'browser',
-  name: 'browser-task',
-  config: {
-    profile: false,
-  },
-});
-const started = await createdRuntime.start();
-console.log(started.run.id, started.browser.cdpUrl);
-
-const invocation = await started.runtime.invocations.create({
-  provider: 'stagehand',
-  method: 'act',
-  input: { instruction: 'Open https://example.com' },
-});
-
-const result = await invocation.wait({ timeoutMs: 60_000 });
-console.log(result.data.status);
-```
-
-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 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.

package/dist/account.d.ts

@@ -0,0 +1,43 @@
+import type { V1HttpClient } from './http.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;
+    constructor(http: V1HttpClient);
+    whoami(): Promise<V1AuthWhoamiResponse>;
+}
+export declare class V1ApiKeysClient {
+    private readonly http;
+    constructor(http: V1HttpClient);
+    list(query?: V1ApiKeyListQuery): Promise<V1ListEnvelope<V1ApiKey>>;
+    iter(query?: V1ApiKeyListQuery): AsyncGenerator<V1ApiKey, void, undefined>;
+    create(request?: V1ApiKeyCreateRequest): Promise<V1ApiKeyCreateResponse>;
+    delete(keyId: string): Promise<V1ApiKeyDeleteResponse>;
+}
+export declare class V1SubaccountUsageClient {
+    private readonly http;
+    constructor(http: V1HttpClient);
+    list(query?: V1SubaccountUsageListQuery): Promise<V1ListEnvelope<V1SubaccountUsage>>;
+    iter(query?: V1SubaccountUsageListQuery): AsyncGenerator<V1SubaccountUsage, void, undefined>;
+}
+export declare class V1SubaccountsClient {
+    private readonly http;
+    readonly usage: V1SubaccountUsageClient;
+    constructor(http: V1HttpClient);
+    list(query?: V1SubaccountListQuery): Promise<V1ListEnvelope<V1Subaccount>>;
+    iter(query?: V1SubaccountListQuery): AsyncGenerator<V1Subaccount, void, undefined>;
+    create(request: V1SubaccountCreateRequest): Promise<V1Subaccount>;
+    get(subaccountId: string, query?: V1SubaccountGetQuery): Promise<V1Subaccount>;
+    update(subaccountId: string, request: V1SubaccountUpdateRequest): Promise<V1Subaccount>;
+    archive(subaccountId: string): Promise<V1SubaccountArchiveResponse>;
+}
+export declare class V1UsageClient {
+    private readonly http;
+    constructor(http: V1HttpClient);
+    get(): Promise<V1AccountUsage>;
+}
+export declare class V1AccountClient {
+    readonly apiKeys: V1ApiKeysClient;
+    readonly subaccounts: V1SubaccountsClient;
+    readonly usage: V1UsageClient;
+    constructor(http: V1HttpClient);
+}

package/dist/account.js

@@ -0,0 +1,100 @@
+import { iterateV1Pages } from './pagination.js';
+export class V1AuthClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    whoami() {
+        return this.http.request('/auth/whoami');
+    }
+}
+export class V1ApiKeysClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(query = {}) {
+        return this.http.request('/api-keys', { query });
+    }
+    iter(query = {}) {
+        return iterateV1Pages(query, (pageQuery) => this.list(pageQuery));
+    }
+    create(request = {}) {
+        return this.http.request('/api-keys', {
+            method: 'POST',
+            body: request,
+        });
+    }
+    delete(keyId) {
+        return this.http.request(`/api-keys/${encodeURIComponent(keyId)}`, {
+            method: 'DELETE',
+        });
+    }
+}
+export class V1SubaccountUsageClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(query = {}) {
+        return this.http.request('/subaccounts/usage', {
+            query,
+        });
+    }
+    iter(query = {}) {
+        return iterateV1Pages(query, (pageQuery) => this.list(pageQuery));
+    }
+}
+export class V1SubaccountsClient {
+    http;
+    usage;
+    constructor(http) {
+        this.http = http;
+        this.usage = new V1SubaccountUsageClient(http);
+    }
+    list(query = {}) {
+        return this.http.request('/subaccounts', { query });
+    }
+    iter(query = {}) {
+        return iterateV1Pages(query, (pageQuery) => this.list(pageQuery));
+    }
+    create(request) {
+        return this.http.request('/subaccounts', {
+            method: 'POST',
+            body: request,
+        });
+    }
+    get(subaccountId, query = {}) {
+        return this.http.request(`/subaccounts/${encodeURIComponent(subaccountId)}`, {
+            query,
+        });
+    }
+    update(subaccountId, request) {
+        return this.http.request(`/subaccounts/${encodeURIComponent(subaccountId)}`, {
+            method: 'PATCH',
+            body: request,
+        });
+    }
+    archive(subaccountId) {
+        return this.http.request(`/subaccounts/${encodeURIComponent(subaccountId)}/archive`, { method: 'POST' });
+    }
+}
+export class V1UsageClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    get() {
+        return this.http.request('/usage');
+    }
+}
+export class V1AccountClient {
+    apiKeys;
+    subaccounts;
+    usage;
+    constructor(http) {
+        this.apiKeys = new V1ApiKeysClient(http);
+        this.subaccounts = new V1SubaccountsClient(http);
+        this.usage = new V1UsageClient(http);
+    }
+}

package/dist/accountTypes.d.ts

@@ -0,0 +1,126 @@
+import type { JsonObject, V1ListEnvelope, V1PageQuery } from './types.js';
+export type V1AuthScope = 'organization' | 'subaccount';
+export type V1Plan = 'free' | 'developer' | 'business' | 'enterprise';
+export interface V1AuthWhoamiResponse {
+    email: string | null;
+    scope: V1AuthScope;
+    organizationId: string;
+    subaccountId: string | null;
+    defaultSpaceId: string;
+    plan: V1Plan;
+    keyId: string;
+}
+export interface V1ApiKey {
+    id: string;
+    keyKind: 'organization' | 'subaccount';
+    subaccountId: string | null;
+    name: string | null;
+    keyPrefix: string;
+    scopes: '*'[];
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    lastUsedAt: string | null;
+    usageCount: number;
+}
+export interface V1ApiKeyListQuery extends V1PageQuery {
+    subaccountId?: string;
+    keyKind?: V1ApiKey['keyKind'];
+}
+export interface V1ApiKeyCreateRequest {
+    name?: string;
+    subaccountId?: string;
+    scopes?: '*'[];
+    expiresAt?: string | null;
+}
+export interface V1ApiKeyCreateResponse {
+    data: V1ApiKey;
+    secret: string;
+}
+export interface V1ApiKeyDeleteResponse {
+    id: string;
+    deleted: true;
+}
+export interface V1AccountUsage {
+    organizationId: string;
+    isBlocked: boolean;
+    blockedReasons: string[];
+    cycle: {
+        startedAt: string | null;
+        endsAt: string | null;
+    };
+    credits: {
+        monthlyLimit: number;
+        monthlyUsed: number;
+        monthlyRemaining: number;
+        purchasedRemaining: number;
+        available: number;
+        outstandingDebt: number;
+        effectiveBalance: number;
+        breakdown: JsonObject;
+    };
+    computedAt: string;
+}
+export interface V1SubaccountLimits {
+    monthlyCredits?: number | null;
+    maxConcurrentRuntimes?: number | null;
+    maxRuntimeMinutes?: number | null;
+}
+export interface V1Subaccount {
+    id: string;
+    name: string;
+    status: 'active' | 'archived';
+    externalId?: string | null;
+    metadata?: JsonObject | null;
+    archivedAt?: string | null;
+    defaultSpaceId: string;
+    limits: V1SubaccountLimits;
+    usage?: V1SubaccountUsage;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface V1SubaccountListQuery extends V1PageQuery {
+    status?: V1Subaccount['status'];
+    externalId?: string;
+}
+export interface V1SubaccountCreateRequest {
+    name: string;
+    externalId?: string;
+    metadata?: JsonObject;
+    limits?: V1SubaccountLimits;
+}
+export interface V1SubaccountUpdateRequest {
+    name?: string;
+    externalId?: string | null;
+    metadata?: JsonObject | null;
+    limits?: V1SubaccountLimits;
+}
+export interface V1SubaccountGetQuery {
+    include?: 'usage' | 'usage'[];
+}
+export interface V1SubaccountArchiveResponse {
+    id: string;
+    archived: true;
+}
+export interface V1SubaccountUsage {
+    subaccountId: string;
+    isBlocked: boolean;
+    blockedReasons: string[];
+    cycle: {
+        startedAt: string | null;
+        endsAt: string | null;
+    };
+    credits: {
+        monthlyLimit: number;
+        monthlyUsed: number;
+        monthlyRemaining: number;
+        purchasedRemaining: number;
+        available: number;
+        breakdown: JsonObject;
+    };
+    computedAt: string;
+}
+export type V1SubaccountUsageListQuery = V1PageQuery & {
+    subaccountId?: string;
+};
+export type V1SubaccountUsageListResponse = V1ListEnvelope<V1SubaccountUsage>;

package/dist/accountTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/ai.d.ts

@@ -0,0 +1,23 @@
+import type { V1HttpClient } from './http.js';
+import type { V1AiCredential, V1AiCredentialCreateRequest, V1AiCredentialDeleteResponse, V1AiCredentialListQuery, V1AiCredentialTestResponse, V1AiCredentialUpdateRequest, V1AiModelListQuery, V1AiModelListResponse, V1ListEnvelope } from './types.js';
+export declare class V1AiModelsClient {
+    private readonly http;
+    constructor(http: V1HttpClient);
+    list(query?: V1AiModelListQuery): Promise<V1AiModelListResponse>;
+}
+export declare class V1AiCredentialsClient {
+    private readonly http;
+    constructor(http: V1HttpClient);
+    list(query?: V1AiCredentialListQuery): Promise<V1ListEnvelope<V1AiCredential>>;
+    iter(query?: V1AiCredentialListQuery): AsyncGenerator<V1AiCredential, void, undefined>;
+    create(request: V1AiCredentialCreateRequest): Promise<V1AiCredential>;
+    get(credentialId: string): Promise<V1AiCredential>;
+    update(credentialId: string, request: V1AiCredentialUpdateRequest): Promise<V1AiCredential>;
+    delete(credentialId: string): Promise<V1AiCredentialDeleteResponse>;
+    test(credentialId: string): Promise<V1AiCredentialTestResponse>;
+}
+export declare class V1AiClient {
+    readonly models: V1AiModelsClient;
+    readonly credentials: V1AiCredentialsClient;
+    constructor(http: V1HttpClient);
+}

package/dist/ai.js

@@ -0,0 +1,51 @@
+import { iterateV1Pages } from './pagination.js';
+export class V1AiModelsClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(query = {}) {
+        return this.http.request('/ai/models', { query });
+    }
+}
+export class V1AiCredentialsClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(query = {}) {
+        return this.http.request('/ai/credentials', { query });
+    }
+    iter(query = {}) {
+        return iterateV1Pages(query, (pageQuery) => this.list(pageQuery));
+    }
+    create(request) {
+        return this.http.request('/ai/credentials', {
+            method: 'POST',
+            body: request,
+        });
+    }
+    get(credentialId) {
+        return this.http.request(`/ai/credentials/${encodeURIComponent(credentialId)}`);
+    }
+    update(credentialId, request) {
+        return this.http.request(`/ai/credentials/${encodeURIComponent(credentialId)}`, {
+            method: 'PATCH',
+            body: request,
+        });
+    }
+    delete(credentialId) {
+        return this.http.request(`/ai/credentials/${encodeURIComponent(credentialId)}`, { method: 'DELETE' });
+    }
+    test(credentialId) {
+        return this.http.request(`/ai/credentials/${encodeURIComponent(credentialId)}/test`, { method: 'POST' });
+    }
+}
+export class V1AiClient {
+    models;
+    credentials;
+    constructor(http) {
+        this.models = new V1AiModelsClient(http);
+        this.credentials = new V1AiCredentialsClient(http);
+    }
+}

package/dist/aiTypes.d.ts

@@ -0,0 +1,97 @@
+import type { JsonObject, V1PageQuery } from './types.js';
+export type V1AiCredentialProvider = 'openai' | 'anthropic' | 'google' | 'azure' | 'groq' | 'deepseek' | 'mistral' | 'cerebras' | 'openrouter' | 'xai' | 'perplexity' | 'togetherai' | 'vercel-ai-gateway' | 'custom';
+export type V1AiModelStatus = 'recommended' | 'supported' | 'experimental';
+export type V1AiModelEngine = 'stagehand' | 'browserUse';
+export interface V1AiModel {
+    id: string;
+    provider: V1AiCredentialProvider;
+    displayName: string;
+    managed: boolean;
+    status: V1AiModelStatus;
+    engines: V1AiModelEngine[];
+    supportsTools: boolean;
+    supportsVision: boolean;
+    supportsStructuredOutput: boolean;
+    supportsReasoningEffort: boolean;
+    supportsThinkingBudget: boolean;
+}
+export interface V1AiModelListQuery {
+    provider?: V1AiCredentialProvider;
+    status?: V1AiModelStatus;
+    managed?: boolean;
+    engine?: V1AiModelEngine;
+}
+export interface V1AiModelListResponse {
+    data: V1AiModel[];
+}
+export type V1AiCredentialStatus = 'enabled' | 'disabled';
+export interface V1AiCredential {
+    id: string;
+    name: string;
+    provider: V1AiCredentialProvider;
+    status: V1AiCredentialStatus;
+    subaccountId?: string;
+    defaultModel?: string;
+    baseUrl?: string;
+    hasApiKey: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface V1AiCredentialListQuery extends V1PageQuery {
+    provider?: V1AiCredentialProvider;
+    name?: string;
+    status?: V1AiCredentialStatus;
+}
+export interface V1AiCredentialCreateRequest {
+    provider: V1AiCredentialProvider;
+    name?: string;
+    apiKey?: string;
+    defaultModel?: string;
+    baseUrl?: string;
+    status?: V1AiCredentialStatus;
+    subaccountId?: string | null;
+    test?: boolean;
+}
+export interface V1AiCredentialUpdateRequest {
+    name?: string;
+    apiKey?: string | null;
+    defaultModel?: string | null;
+    baseUrl?: string | null;
+    status?: V1AiCredentialStatus;
+}
+export interface V1AiCredentialDeleteResponse {
+    id: string;
+    deleted: true;
+}
+export interface V1AiCredentialTestResponse {
+    ok: boolean;
+    checkedAt: string;
+    latencyMs?: number;
+    error?: string;
+}
+export type V1AiModelSelectionAuth = 'managed' | {
+    credential: string;
+} | {
+    apiKey: string;
+};
+export interface V1AiModelSelectionObject {
+    model: string;
+    auth?: V1AiModelSelectionAuth;
+    provider?: V1AiCredentialProvider;
+    baseUrl?: string;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    reasoningEffort?: 'none' | 'low' | 'medium' | 'high' | 'xhigh';
+    thinkingBudgetTokens?: number;
+    responseFormat?: 'text' | 'json';
+    responseSchema?: JsonObject;
+    providerOptions?: JsonObject;
+}
+export type V1AiModelSelection = string | V1AiModelSelectionObject;
+export type V1AiStoredModelSelectionAuth = 'managed' | {
+    credential: string;
+};
+export type V1AiStoredModelSelection = string | (Omit<V1AiModelSelectionObject, 'auth' | 'baseUrl'> & {
+    auth?: V1AiStoredModelSelectionAuth;
+});

package/dist/aiTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/bctrl.d.ts

@@ -1,23 +1,55 @@
+import { V1AccountClient, V1ApiKeysClient, V1AuthClient, V1SubaccountsClient, V1UsageClient } from './account.js';
+import { V1AiClient } from './ai.js';
+import { V1BrowserExtensionsClient } from './browserExtensions.js';
 import { V1FilesClient } from './files.js';
+import { V1HelpClient } from './help.js';
 import { type V1ClientOptions } from './http.js';
-import { V1InvocationsClient } from './invocations.js';
+import { V1ProxiesClient } from './proxies.js';
 import { V1RunsClient } from './runs.js';
 import { V1RuntimesClient } from './runtimes.js';
 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';
 export type BctrlV1Options = V1ClientOptions;
 export declare class BctrlV1 {
     private readonly http;
     private _spaces;
     private _runtimes;
     private _runs;
-    private _invocations;
     private _files;
+    private _help;
+    private _tools;
+    private _toolsets;
+    private _toolCalls;
+    private _vault;
+    private _proxies;
+    private _browserExtensions;
+    private _ai;
+    private _account;
+    private _apiKeys;
+    private _auth;
+    private _subaccounts;
+    private _usage;
     static isControllerBusy(error: unknown): boolean;
     constructor(options?: BctrlV1Options);
     get spaces(): V1SpacesClient;
     get runtimes(): V1RuntimesClient;
     get runs(): V1RunsClient;
-    get invocations(): V1InvocationsClient;
     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;
+    get account(): V1AccountClient;
+    get apiKeys(): V1ApiKeysClient;
+    get auth(): V1AuthClient;
+    get subaccounts(): V1SubaccountsClient;
+    get usage(): V1UsageClient;
 }
 export { BctrlV1 as Bctrl };