@bctrl/sdk 1.0.5 → 1.0.7

package/README.md

@@ -1,71 +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',
-});
-
-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/accountTypes.d.ts

@@ -1,126 +1,20 @@
-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>;
+import type { OpenApiQuery, OpenApiSchemas } from './openapi.js';
+export type V1AuthScope = OpenApiSchemas['AuthWhoamiResponse']['scope'];
+export type V1Plan = OpenApiSchemas['AuthWhoamiResponse']['plan'];
+export type V1AuthWhoamiResponse = OpenApiSchemas['AuthWhoamiResponse'];
+export type V1ApiKey = OpenApiSchemas['ApiKey'];
+export type V1ApiKeyListQuery = OpenApiQuery<'api-keys.list'>;
+export type V1ApiKeyCreateRequest = OpenApiSchemas['ApiKeyCreateRequest'];
+export type V1ApiKeyCreateResponse = OpenApiSchemas['ApiKeyCreateResponse'];
+export type V1ApiKeyDeleteResponse = OpenApiSchemas['ApiKeyDeleteResponse'];
+export type V1AccountUsage = OpenApiSchemas['AccountUsage'];
+export type V1SubaccountLimits = OpenApiSchemas['SubaccountLimits'];
+export type V1Subaccount = OpenApiSchemas['Subaccount'];
+export type V1SubaccountListQuery = OpenApiQuery<'subaccounts.list'>;
+export type V1SubaccountCreateRequest = OpenApiSchemas['SubaccountCreateRequest'];
+export type V1SubaccountUpdateRequest = OpenApiSchemas['SubaccountUpdateRequest'];
+export type V1SubaccountGetQuery = OpenApiQuery<'subaccounts.get'>;
+export type V1SubaccountArchiveResponse = OpenApiSchemas['SubaccountArchiveResponse'];
+export type V1SubaccountUsage = OpenApiSchemas['SubaccountUsage'];
+export type V1SubaccountUsageListQuery = OpenApiQuery<'subaccounts.usage.list'>;
+export type V1SubaccountUsageListResponse = OpenApiSchemas['SubaccountUsageListResponse'];

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,19 @@
+import type { OpenApiQuery, OpenApiSchemas } from './openapi.js';
+export type V1AiCredentialProvider = OpenApiSchemas['AiCredential']['provider'];
+export type V1AiModelStatus = OpenApiSchemas['AiModel']['status'];
+export type V1AiModelEngine = OpenApiSchemas['AiModel']['engines'][number];
+export type V1AiModel = OpenApiSchemas['AiModel'];
+export type V1AiModelListQuery = OpenApiQuery<'ai.models.list'>;
+export type V1AiModelListResponse = OpenApiSchemas['AiModelListResponse'];
+export type V1AiCredentialStatus = OpenApiSchemas['AiCredential']['status'];
+export type V1AiCredential = OpenApiSchemas['AiCredential'];
+export type V1AiCredentialListQuery = OpenApiQuery<'ai.credentials.list'>;
+export type V1AiCredentialCreateRequest = OpenApiSchemas['AiCredentialCreateRequest'];
+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,5 +1,5 @@
 import { V1AccountClient, V1ApiKeysClient, V1AuthClient, V1SubaccountsClient, V1UsageClient } from './account.js';
-import { V1AiProvidersClient } from './aiProviders.js';
+import { V1AiClient } from './ai.js';
 import { V1BrowserExtensionsClient } from './browserExtensions.js';
 import { V1FilesClient } from './files.js';
 import { V1HelpClient } from './help.js';
@@ -26,7 +26,7 @@ export declare class BctrlV1 {
     private _vault;
     private _proxies;
     private _browserExtensions;
-    private _aiProviders;
+    private _ai;
     private _account;
     private _apiKeys;
     private _auth;
@@ -45,7 +45,7 @@ export declare class BctrlV1 {
     get vault(): V1VaultClient;
     get proxies(): V1ProxiesClient;
     get browserExtensions(): V1BrowserExtensionsClient;
-    get aiProviders(): V1AiProvidersClient;
+    get ai(): V1AiClient;
     get account(): V1AccountClient;
     get apiKeys(): V1ApiKeysClient;
     get auth(): V1AuthClient;

package/dist/bctrl.js

@@ -1,5 +1,5 @@
 import { V1AccountClient, V1ApiKeysClient, V1AuthClient, V1SubaccountsClient, V1UsageClient, } from './account.js';
-import { V1AiProvidersClient } from './aiProviders.js';
+import { V1AiClient } from './ai.js';
 import { V1BrowserExtensionsClient } from './browserExtensions.js';
 import { isControllerBusy } from './errors.js';
 import { V1FilesClient } from './files.js';
@@ -26,7 +26,7 @@ export class BctrlV1 {
     _vault = null;
     _proxies = null;
     _browserExtensions = null;
-    _aiProviders = null;
+    _ai = null;
     _account = null;
     _apiKeys = null;
     _auth = null;
@@ -82,9 +82,9 @@ export class BctrlV1 {
         this._browserExtensions ??= new V1BrowserExtensionsClient(this.http);
         return this._browserExtensions;
     }
-    get aiProviders() {
-        this._aiProviders ??= new V1AiProvidersClient(this.http);
-        return this._aiProviders;
+    get ai() {
+        this._ai ??= new V1AiClient(this.http);
+        return this._ai;
     }
     get account() {
         this._account ??= new V1AccountClient(this.http);

package/dist/browserExtensionTypes.d.ts

@@ -1,25 +1,8 @@
-import type { V1PageQuery } from './types.js';
-export type V1BrowserExtensionFormat = 'crx';
+import type { OpenApiQuery, OpenApiSchemas } from './openapi.js';
+export type V1BrowserExtensionFormat = OpenApiSchemas['BrowserExtension']['format'];
 export type V1BrowserExtensionSource = 'upload' | 'url';
-export interface V1BrowserExtension {
-    id: string;
-    name: string;
-    version: string;
-    format: V1BrowserExtensionFormat;
-    subaccountId?: string;
-    sourceUrl?: string;
-    sizeBytes?: number;
-    contentHash?: string;
-    profileCount: number;
-    createdAt: string;
-    updatedAt: string;
-}
-export interface V1BrowserExtensionListQuery extends V1PageQuery {
-    subaccountId?: string;
-    q?: string;
-    format?: V1BrowserExtensionFormat;
-    source?: V1BrowserExtensionSource;
-}
+export type V1BrowserExtension = OpenApiSchemas['BrowserExtension'];
+export type V1BrowserExtensionListQuery = OpenApiQuery<'browser-extensions.list'>;
 export interface V1BrowserExtensionUploadRequest {
     /** Packed Chromium extension package. Only .crx is supported today. */
     file: Blob;
@@ -28,18 +11,6 @@ export interface V1BrowserExtensionUploadRequest {
     /** Parent/org keys may create inside a child subaccount. */
     subaccountId?: string;
 }
-export interface V1BrowserExtensionImportRequest {
-    /** Chrome Web Store detail URL. */
-    url: string;
-    /** Optional display name. Defaults to manifest.name. */
-    name?: string;
-    /** Parent/org keys may create inside a child subaccount. */
-    subaccountId?: string;
-}
-export interface V1BrowserExtensionUpdateRequest {
-    name: string;
-}
-export interface V1BrowserExtensionDeleteResponse {
-    id: string;
-    deleted: true;
-}
+export type V1BrowserExtensionImportRequest = OpenApiSchemas['BrowserExtensionImportRequest'];
+export type V1BrowserExtensionUpdateRequest = OpenApiSchemas['BrowserExtensionUpdateRequest'];
+export type V1BrowserExtensionDeleteResponse = OpenApiSchemas['BrowserExtensionDeleteResponse'];

package/dist/files.d.ts

@@ -1,9 +1,9 @@
 import type { V1HttpClient } from './http.js';
-import type { V1File, V1FileDeleteResponse, V1FilesListQuery, V1FileUpdateRequest, V1FileUploadRequest, V1ListEnvelope } from './types.js';
+import type { V1File, V1FileDeleteResponse, V1FilesListQuery, V1FilesListResponse, V1FileUpdateRequest, V1FileUploadRequest } from './types.js';
 export declare class V1FilesClient {
     private readonly http;
     constructor(http: V1HttpClient);
-    list(query?: V1FilesListQuery): Promise<V1ListEnvelope<V1File>>;
+    list(query?: V1FilesListQuery): Promise<V1FilesListResponse>;
     iter(query?: V1FilesListQuery): AsyncGenerator<V1File, void, undefined>;
     get(id: string): Promise<V1File>;
     update(id: string, request: V1FileUpdateRequest): Promise<V1File>;