@bctrl/sdk 1.0.4 → 1.0.5

package/dist/invocations.js

@@ -1,55 +1,40 @@
-export class V1InvocationResource {
-    http;
-    data;
-    constructor(http, data) {
-        this.http = http;
-        this.data = data;
-    }
-    get id() {
-        return this.data.id;
-    }
-    refresh() {
-        return this.http
-            .request(`/invocations/${encodeURIComponent(this.id)}`)
-            .then((response) => response.data);
-    }
-    wait(request) {
-        return this.http.request(`/invocations/${encodeURIComponent(this.id)}/wait`, {
-            method: 'POST',
-            body: request ?? {},
-        });
-    }
-    cancel() {
-        return this.http
-            .request(`/invocations/${encodeURIComponent(this.id)}/cancel`, {
-            method: 'POST',
-        })
-            .then((response) => response.data);
-    }
+import { v1IdempotencyHeaders } from './http.js';
+import { toOutputSchema } from './schemas.js';
+import { abortableSleep } from './utils.js';
+// Live control is runtime-scoped; observability reads are run-scoped.
+function runtimeInvocationActionPath(runtimeId, invocationId, action) {
+    return `/runtimes/${encodeURIComponent(runtimeId)}/invocations/${encodeURIComponent(invocationId)}/${action}`;
 }
-export class V1InvocationsClient {
+function createRuntimeInvocation(http, runtimeId, request, options) {
+    return http.request(`/runtimes/${encodeURIComponent(runtimeId)}/invocations`, {
+        method: 'POST',
+        body: prepareInvocationCreateRequest(request),
+        headers: v1IdempotencyHeaders(options),
+    });
+}
+export class V1RuntimeInvocationsNamespaceClient {
     http;
+    stagehand;
+    browserUse;
     constructor(http) {
         this.http = http;
+        this.stagehand = new V1RuntimeStagehandInvocationsNamespaceClient(this);
+        this.browserUse = new V1RuntimeBrowserUseInvocationsNamespaceClient(this);
     }
-    async get(id) {
-        const response = await this.http.request(`/invocations/${encodeURIComponent(id)}`);
-        return new V1InvocationResource(this.http, response.data);
+    create(runtimeId, request, options) {
+        return createRuntimeInvocation(this.http, runtimeId, request, options);
     }
-    wait(id, request) {
-        return this.http.request(`/invocations/${encodeURIComponent(id)}/wait`, {
-            method: 'POST',
-            body: request ?? {},
-        });
+    wait(runtimeId, invocationId, request = {}) {
+        return new V1RuntimeInvocationsClient(this.http, runtimeId).wait(invocationId, request);
     }
-    async cancel(id) {
-        const response = await this.http.request(`/invocations/${encodeURIComponent(id)}/cancel`, {
-            method: 'POST',
-        });
-        return new V1InvocationResource(this.http, response.data);
+    cancel(runtimeId, invocationId) {
+        return new V1RuntimeInvocationsClient(this.http, runtimeId).cancel(invocationId);
+    }
+    createAndWait(runtimeId, request, options = {}) {
+        return new V1RuntimeInvocationsClient(this.http, runtimeId).createAndWait(request, options);
     }
 }
-export class V1RuntimeInvocationsClient {
+class V1RuntimeInvocationsClient {
     http;
     runtimeId;
     stagehand;
@@ -60,100 +45,157 @@ export class V1RuntimeInvocationsClient {
         this.stagehand = new V1RuntimeStagehandInvocationsClient(this);
         this.browserUse = new V1RuntimeBrowserUseInvocationsClient(this);
     }
-    async create(request) {
-        const response = await this.http.request(`/runtimes/${encodeURIComponent(this.runtimeId)}/invocations`, {
+    async create(request, options) {
+        return createRuntimeInvocation(this.http, this.runtimeId, request, options);
+    }
+    wait(invocationId, request = {}) {
+        const { signal, ...body } = request;
+        return this.http.request(runtimeInvocationActionPath(this.runtimeId, invocationId, 'wait'), {
             method: 'POST',
-            body: request,
+            body,
+            signal,
         });
-        return new V1InvocationResource(this.http, response.data);
+    }
+    cancel(invocationId) {
+        return this.http.request(runtimeInvocationActionPath(this.runtimeId, invocationId, 'cancel'), {
+            method: 'POST',
+        });
+    }
+    async createAndWait(request, options = {}) {
+        const invocation = await this.create(request, options);
+        return waitForInvocation(this, invocation.id, options);
     }
 }
-export class V1RuntimeStagehandInvocationsClient {
+class V1RuntimeStagehandInvocationsClient {
     invocations;
     constructor(invocations) {
         this.invocations = invocations;
     }
     act(options) {
-        const { instruction, timeoutMs, ...common } = options;
         return this.invocations.create({
-            provider: 'stagehand',
-            method: 'act',
-            ...common,
-            input: {
-                instruction,
-                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-            },
+            action: 'act',
+            ...options,
         });
     }
     observe(options) {
-        const { instruction, selector, timeoutMs, ...common } = options;
         return this.invocations.create({
-            provider: 'stagehand',
-            method: 'observe',
-            ...common,
-            input: {
-                instruction,
-                ...(selector !== undefined ? { selector } : {}),
-                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-            },
+            action: 'observe',
+            ...options,
         });
     }
     extract(options) {
-        const { instruction, schema, ...common } = options;
+        const { schema, ...common } = options;
         return this.invocations.create({
-            provider: 'stagehand',
-            method: 'extract',
+            action: 'extract',
             ...common,
-            input: { instruction },
-            ...(schema !== undefined ? { outputSchema: toJsonSchemaObject(schema) } : {}),
+            ...(schema !== undefined
+                ? { outputSchema: toOutputSchema(schema, 'Stagehand extract schema') }
+                : {}),
         });
     }
     agent(options) {
-        const { instruction, maxSteps, timeoutMs, variables, config, options: agentOptions, ...common } = options;
         return this.invocations.create({
-            provider: 'stagehand',
-            method: 'agent',
-            ...common,
-            input: {
-                instruction,
-                ...(maxSteps !== undefined ? { maxSteps } : {}),
-                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-                ...(variables !== undefined ? { variables } : {}),
-            },
-            ...(config !== undefined ? { config } : {}),
-            ...(agentOptions !== undefined ? { options: agentOptions } : {}),
+            action: 'stagehandAgent',
+            ...options,
         });
     }
 }
-export class V1RuntimeBrowserUseInvocationsClient {
+class V1RuntimeBrowserUseInvocationsClient {
     invocations;
     constructor(invocations) {
         this.invocations = invocations;
     }
     agent(options) {
-        const { instruction, maxSteps, config, options: agentOptions, ...common } = options;
         return this.invocations.create({
-            provider: 'browserUse',
-            method: 'agent',
+            action: 'browserUse',
+            ...options,
+        });
+    }
+}
+export class V1RuntimeStagehandInvocationsNamespaceClient {
+    invocations;
+    constructor(invocations) {
+        this.invocations = invocations;
+    }
+    act(runtimeId, options) {
+        return this.invocations.create(runtimeId, {
+            action: 'act',
+            ...options,
+        });
+    }
+    observe(runtimeId, options) {
+        return this.invocations.create(runtimeId, {
+            action: 'observe',
+            ...options,
+        });
+    }
+    extract(runtimeId, options) {
+        const { schema, ...common } = options;
+        return this.invocations.create(runtimeId, {
+            action: 'extract',
             ...common,
-            input: {
-                instruction,
-                ...(maxSteps !== undefined ? { maxSteps } : {}),
-            },
-            ...(config !== undefined ? { config } : {}),
-            ...(agentOptions !== undefined ? { options: agentOptions } : {}),
+            ...(schema !== undefined
+                ? { outputSchema: toOutputSchema(schema, 'Stagehand extract schema') }
+                : {}),
+        });
+    }
+    agent(runtimeId, options) {
+        return this.invocations.create(runtimeId, {
+            action: 'stagehandAgent',
+            ...options,
+        });
+    }
+}
+export class V1RuntimeBrowserUseInvocationsNamespaceClient {
+    invocations;
+    constructor(invocations) {
+        this.invocations = invocations;
+    }
+    agent(runtimeId, options) {
+        return this.invocations.create(runtimeId, {
+            action: 'browserUse',
+            ...options,
         });
     }
 }
-function toJsonSchemaObject(schema) {
-    const value = typeof schema.toJSONSchema === 'function' ? schema.toJSONSchema() : schema;
-    if (!isJsonObject(value)) {
-        throw new TypeError('Stagehand extract schema must resolve to a JSON object');
-    }
-    const { $schema, ...jsonSchema } = value;
-    void $schema;
-    return jsonSchema;
+function prepareInvocationCreateRequest(request) {
+    if (!hasInvocationSchema(request)) {
+        return request;
+    }
+    if ('outputSchema' in request && request.outputSchema !== undefined) {
+        throw new TypeError('Pass either schema or outputSchema, not both');
+    }
+    const { schema, ...body } = request;
+    return {
+        ...body,
+        outputSchema: toOutputSchema(schema, 'Invocation schema'),
+    };
 }
-function isJsonObject(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
+function hasInvocationSchema(request) {
+    return 'schema' in request && request.schema !== undefined;
+}
+async function waitForInvocation(client, invocationId, options) {
+    const deadline = options.timeoutMs === undefined ? undefined : Date.now() + options.timeoutMs;
+    for (;;) {
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new Error(`Invocation ${invocationId} did not finish before timeout`);
+        }
+        const remaining = deadline === undefined ? undefined : Math.max(1, deadline - Date.now());
+        const timeoutMs = options.pollTimeoutMs === undefined
+            ? remaining
+            : remaining === undefined
+                ? options.pollTimeoutMs
+                : Math.min(options.pollTimeoutMs, remaining);
+        const result = await client.wait(invocationId, {
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            signal: options.signal,
+        });
+        if (result.waitStatus === 'completed') {
+            return result;
+        }
+        const sleepMs = deadline === undefined
+            ? (result.retryAfterMs ?? 1000)
+            : Math.min(result.retryAfterMs ?? 1000, Math.max(0, deadline - Date.now()));
+        await abortableSleep(sleepMs, options.signal);
+    }
 }

package/dist/node.d.ts

@@ -0,0 +1,12 @@
+import { BctrlV1 } from './bctrl.js';
+import type { V1ToolCreateRequest, V1ToolVersionCreateRequest } from './types.js';
+type V1HostedToolCreateRequest = Extract<V1ToolCreateRequest, {
+    type: 'hosted';
+}>;
+export declare function createHostedToolFromFile(client: BctrlV1, request: Omit<V1HostedToolCreateRequest, 'source'> & {
+    filePath: string;
+}): Promise<import("./types.js").V1Tool>;
+export declare function createToolVersionFromFile(client: BctrlV1, toolId: string, request: Omit<V1ToolVersionCreateRequest, 'source'> & {
+    filePath: string;
+}): Promise<import("./types.js").V1ToolVersion>;
+export {};

package/dist/node.js

@@ -0,0 +1,11 @@
+import { readFile } from 'node:fs/promises';
+export async function createHostedToolFromFile(client, request) {
+    const source = await readFile(request.filePath, 'utf8');
+    const { filePath: _filePath, ...rest } = request;
+    return client.tools.create({ ...rest, source });
+}
+export async function createToolVersionFromFile(client, toolId, request) {
+    const source = await readFile(request.filePath, 'utf8');
+    const { filePath: _filePath, ...rest } = request;
+    return client.tools.createVersion(toolId, { ...rest, source });
+}

package/dist/proxies.d.ts

@@ -0,0 +1,21 @@
+import type { V1HttpClient } from './http.js';
+import type { V1ListEnvelope, V1Proxy, V1ProxyCreateRequest, V1ProxyDeleteResponse, V1ProxyListQuery, V1ProxyPool, V1ProxyPoolListQuery, V1ProxyTestResponse, V1ProxyUpdateRequest } from './types.js';
+export declare class V1ProxyPoolsClient {
+    private readonly http;
+    constructor(http: V1HttpClient);
+    list(query?: V1ProxyPoolListQuery): Promise<V1ListEnvelope<V1ProxyPool>>;
+    iter(query?: V1ProxyPoolListQuery): AsyncGenerator<V1ProxyPool, void, undefined>;
+    get(poolId: string): Promise<V1ProxyPool>;
+}
+export declare class V1ProxiesClient {
+    private readonly http;
+    readonly pools: V1ProxyPoolsClient;
+    constructor(http: V1HttpClient);
+    list(query?: V1ProxyListQuery): Promise<V1ListEnvelope<V1Proxy>>;
+    iter(query?: V1ProxyListQuery): AsyncGenerator<V1Proxy, void, undefined>;
+    create(request: V1ProxyCreateRequest): Promise<V1Proxy>;
+    get(proxyId: string): Promise<V1Proxy>;
+    update(proxyId: string, request: V1ProxyUpdateRequest): Promise<V1Proxy>;
+    test(proxyId: string): Promise<V1ProxyTestResponse>;
+    delete(proxyId: string): Promise<V1ProxyDeleteResponse>;
+}

package/dist/proxies.js

@@ -0,0 +1,55 @@
+import { iterateV1Pages } from './pagination.js';
+export class V1ProxyPoolsClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(query = {}) {
+        return this.http.request('/proxies/pools', { query });
+    }
+    iter(query = {}) {
+        return iterateV1Pages(query, (pageQuery) => this.list(pageQuery));
+    }
+    get(poolId) {
+        return this.http.request(`/proxies/pools/${encodeURIComponent(poolId)}`);
+    }
+}
+export class V1ProxiesClient {
+    http;
+    pools;
+    constructor(http) {
+        this.http = http;
+        this.pools = new V1ProxyPoolsClient(http);
+    }
+    list(query = {}) {
+        return this.http.request('/proxies', { query });
+    }
+    iter(query = {}) {
+        return iterateV1Pages(query, (pageQuery) => this.list(pageQuery));
+    }
+    create(request) {
+        return this.http.request('/proxies', {
+            method: 'POST',
+            body: request,
+        });
+    }
+    get(proxyId) {
+        return this.http.request(`/proxies/${encodeURIComponent(proxyId)}`);
+    }
+    update(proxyId, request) {
+        return this.http.request(`/proxies/${encodeURIComponent(proxyId)}`, {
+            method: 'PATCH',
+            body: request,
+        });
+    }
+    test(proxyId) {
+        return this.http.request(`/proxies/${encodeURIComponent(proxyId)}/test`, {
+            method: 'POST',
+        });
+    }
+    delete(proxyId) {
+        return this.http.request(`/proxies/${encodeURIComponent(proxyId)}`, {
+            method: 'DELETE',
+        });
+    }
+}

package/dist/proxyTypes.d.ts

@@ -0,0 +1,114 @@
+export type V1ProxyProtocol = 'http' | 'socks5';
+export type V1ProxyType = 'custom' | 'managed-rotating' | 'managed-static';
+export type V1ManagedRotatingPreference = 'balanced' | 'speed' | 'quality' | 'coverage';
+export type V1ManagedRotatingRotation = 'sticky' | 'rotating';
+export type V1ManagedRotatingDevice = 'windows' | 'macos' | 'linux' | 'android' | 'ios';
+export interface V1ProxyBase {
+    id: string;
+    name: string;
+    subaccountId?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface V1ManagedRotatingProxyConfig {
+    protocol?: V1ProxyProtocol;
+    ipFamily?: 'dual-stack' | 'ipv4-only';
+    preference?: V1ManagedRotatingPreference;
+    rotation?: V1ManagedRotatingRotation;
+    stickyKey?: string;
+    country?: string;
+    region?: string;
+    state?: string;
+    city?: string;
+    isp?: string;
+    geoStrict?: boolean;
+    device?: V1ManagedRotatingDevice;
+    deviceStrict?: boolean;
+}
+export type V1Proxy = (V1ProxyBase & {
+    type: 'custom';
+    protocol: V1ProxyProtocol;
+    host: string;
+    port: number;
+    username?: string | null;
+    hasPassword: boolean;
+}) | (V1ProxyBase & V1ManagedRotatingProxyConfig & {
+    type: 'managed-rotating';
+}) | (V1ProxyBase & {
+    type: 'managed-static';
+    status: 'provisioning' | 'active' | 'expired' | 'renewal_failed';
+    poolId: string;
+    autoRenew: boolean;
+    assignedIp?: string;
+    location?: {
+        country: string;
+        city?: string;
+    };
+    expiresAt?: string;
+    renewsAt?: string | null;
+    pricing?: {
+        priceCredits: number;
+        termDays: number;
+    };
+});
+export type V1ProxyCreateRequest = {
+    type: 'custom';
+    name?: string;
+    url?: string;
+    protocol?: V1ProxyProtocol;
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+} | ({
+    type: 'managed-rotating';
+    name?: string;
+} & V1ManagedRotatingProxyConfig) | {
+    type: 'managed-static';
+    name?: string;
+    poolId: string;
+    autoRenew?: boolean;
+};
+export interface V1ProxyUpdateRequest extends Partial<V1ManagedRotatingProxyConfig> {
+    name?: string;
+    url?: string;
+    protocol?: V1ProxyProtocol;
+    host?: string;
+    port?: number;
+    username?: string | null;
+    password?: string | null;
+    autoRenew?: boolean;
+}
+interface V1ProxyPageQuery {
+    cursor?: string;
+    limit?: number;
+}
+export interface V1ProxyListQuery extends V1ProxyPageQuery {
+}
+export interface V1ProxyDeleteResponse {
+    id: string;
+    deleted: true;
+}
+export interface V1ProxyTestResponse {
+    ok: boolean;
+    latencyMs?: number;
+    error?: string;
+    httpStatus?: number | null;
+    exitIp?: string | null;
+    country?: string | null;
+}
+export interface V1ProxyPool {
+    id: string;
+    label: string;
+    country: string;
+    category: 'tickets' | 'sneakers' | 'social' | 'retail';
+    termDays: number;
+    priceCredits: number;
+    availableCount: number;
+}
+export interface V1ProxyPoolListQuery extends V1ProxyPageQuery {
+    country?: string;
+    category?: V1ProxyPool['category'];
+    available?: boolean;
+}
+export {};

package/dist/proxyTypes.js

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

package/dist/runs.d.ts

@@ -1,40 +1,44 @@
-import type { V1HttpClient } from './http.js';
-import { V1RunFilesClient } from './files.js';
-import type { V1ListEnvelope, V1Run, V1RunCommand, V1RunCommandsListQuery, V1RunEvent, V1RunEventsListQuery, V1RunEventsWaitRequest, V1RunEventsWaitResponse, V1RunListQuery, V1RunLiveRequest, V1RunLiveResponse, V1RunRecordingRequest, V1RunRecordingResponse, V1RuntimeStartRun, V1RunUsage } from './types.js';
-export declare class V1RunEventsClient {
+import { type V1HttpClient, type V1IdempotencyOptions } from './http.js';
+import type { V1ListEnvelope, V1File, V1InvocationSummary, V1Run, V1RunEvent, V1RunEventsListQuery, V1RunListQuery, V1RunLiveRequest, V1RunLiveResponse, V1RunRecordingRequest, V1RunRecordingResponse, V1RunActivityItem, V1RunActivityListQuery, V1RunFilesExportRequest, V1RunFilesListQuery, V1RunInvocationsListQuery, V1RunUsage } from './types.js';
+export declare class V1RunsClient {
+    private readonly http;
+    readonly events: V1RunEventsNamespaceClient;
+    readonly activity: V1RunActivityNamespaceClient;
+    readonly files: V1RunFilesNamespaceClient;
+    readonly invocations: V1RunInvocationsNamespaceClient;
+    constructor(http: V1HttpClient);
+    list(query?: V1RunListQuery): Promise<V1ListEnvelope<V1Run>>;
+    iter(query?: V1RunListQuery): AsyncGenerator<V1Run, void, undefined>;
+    get(id: string): Promise<V1Run>;
+    usage(id: string): Promise<V1RunUsage>;
+    live(id: string, request?: V1RunLiveRequest): Promise<V1RunLiveResponse>;
+    recording(id: string, request?: V1RunRecordingRequest): Promise<V1RunRecordingResponse>;
+}
+export declare class V1RunEventsNamespaceClient {
     private readonly http;
-    private readonly runId;
-    constructor(http: V1HttpClient, runId: string);
-    list(query?: V1RunEventsListQuery): Promise<V1ListEnvelope<V1RunEvent>>;
-    iter(query?: V1RunEventsListQuery): AsyncGenerator<V1RunEvent, void, undefined>;
-    wait(request?: V1RunEventsWaitRequest): Promise<V1RunEventsWaitResponse>;
-    streamUrl(query?: Pick<V1RunEventsListQuery, 'type' | 'category' | 'connectionId'>): string;
+    constructor(http: V1HttpClient);
+    list(runId: string, query?: V1RunEventsListQuery): Promise<V1ListEnvelope<V1RunEvent>>;
+    iter(runId: string, query?: V1RunEventsListQuery): AsyncGenerator<V1RunEvent, void, undefined>;
+    streamUrl(runId: string, query?: Pick<V1RunEventsListQuery, 'type' | 'status' | 'pageId' | 'contextId'>): string;
 }
-export declare class V1RunCommandsClient {
+export declare class V1RunActivityNamespaceClient {
     private readonly http;
-    private readonly runId;
-    constructor(http: V1HttpClient, runId: string);
-    list(query?: V1RunCommandsListQuery): Promise<V1ListEnvelope<V1RunCommand>>;
-    iter(query?: V1RunCommandsListQuery): AsyncGenerator<V1RunCommand, void, undefined>;
+    constructor(http: V1HttpClient);
+    list(runId: string, query?: V1RunActivityListQuery): Promise<V1ListEnvelope<V1RunActivityItem>>;
+    iter(runId: string, query?: V1RunActivityListQuery): AsyncGenerator<V1RunActivityItem, void, undefined>;
+    streamUrl(runId: string, query?: V1RunActivityListQuery): string;
 }
-export declare class V1RunResource {
+export declare class V1RunFilesNamespaceClient {
     private readonly http;
-    readonly data: V1Run | V1RuntimeStartRun;
-    readonly events: V1RunEventsClient;
-    readonly commands: V1RunCommandsClient;
-    readonly files: V1RunFilesClient;
-    constructor(http: V1HttpClient, data: V1Run | V1RuntimeStartRun);
-    get id(): string;
-    refresh(): Promise<V1RunResource>;
-    live(request?: V1RunLiveRequest): Promise<V1RunLiveResponse>;
-    recording(request?: V1RunRecordingRequest): Promise<V1RunRecordingResponse>;
-    usage(): Promise<V1RunUsage>;
+    constructor(http: V1HttpClient);
+    list(runId: string, query?: V1RunFilesListQuery): Promise<V1ListEnvelope<V1File>>;
+    iter(runId: string, query?: V1RunFilesListQuery): AsyncGenerator<V1File, void, undefined>;
+    export(runId: string, request?: V1RunFilesExportRequest, options?: V1IdempotencyOptions): Promise<V1File>;
 }
-export declare class V1RunsClient {
+export declare class V1RunInvocationsNamespaceClient {
     private readonly http;
     constructor(http: V1HttpClient);
-    list(query?: V1RunListQuery): Promise<V1ListEnvelope<V1Run>>;
-    iter(query?: V1RunListQuery): AsyncGenerator<V1Run, void, undefined>;
-    get(id: string): Promise<V1RunResource>;
-    usage(id: string): Promise<V1RunUsage>;
+    list(runId: string, query?: V1RunInvocationsListQuery): Promise<V1ListEnvelope<V1InvocationSummary>>;
+    iter(runId: string, query?: V1RunInvocationsListQuery): AsyncGenerator<V1InvocationSummary, void, undefined>;
+    get(runId: string, invocationId: string): Promise<import("./types.js").V1Invocation>;
 }