@boatdev/sdk 1.0.0

package/dist/apis/index.d.ts

@@ -0,0 +1 @@
+export * from './BoatApi';

package/dist/apis/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/* tslint:disable */
+/* eslint-disable */
+__exportStar(require("./BoatApi"), exports);

package/dist/boat-helpers.d.ts

@@ -0,0 +1,56 @@
+import { BoatApi } from './apis/BoatApi';
+import type { Sandbox, SandboxEvent, DesktopResponse, PromptRequest, PromptRun } from './models';
+export type WaitOptions = {
+    timeoutMs?: number;
+    intervalMs?: number;
+};
+export type StreamEventsOptions = WaitOptions & {
+    type?: string;
+    limit?: number;
+    includeExisting?: boolean;
+    signal?: AbortSignal;
+};
+export type StreamPromptOptions = WaitOptions & {
+    signal?: AbortSignal;
+};
+export declare function waitUntilReady(api: BoatApi, sandboxId: string, options?: WaitOptions): Promise<Sandbox>;
+export declare function waitUntilIdle(api: BoatApi, sandboxId: string, options?: WaitOptions): Promise<Sandbox>;
+export declare function waitForDesktop(api: BoatApi, sandboxId: string, options?: WaitOptions & {
+    vnc?: number;
+    publicAccess?: boolean;
+}): Promise<DesktopResponse>;
+export declare function waitForPrompt(api: BoatApi, sandboxId: string, promptId: string, options?: WaitOptions): Promise<PromptRun>;
+export declare const waitForPromptDone: typeof waitForPrompt;
+/**
+ * Long-poll sandbox events and yield each new event once.
+ *
+ * The v1 API does not require a separate SSE/WebSocket connection. This helper
+ * polls `events({ sort: "asc" })`, advances a cursor after every event, and
+ * yields response events as soon as they are persisted. Streaming response
+ * partials have `event.data.isStreaming === true` (or `is_streaming` in raw
+ * JSON); tool-call events are response events whose `event.data.tools` array is
+ * present.
+ */
+export declare function streamEvents(api: BoatApi, sandboxId: string, options?: StreamEventsOptions): AsyncGenerator<SandboxEvent>;
+/**
+ * Queue a prompt, then yield its prompt/response/tool events until the prompt
+ * reaches `finished` or `failed`.
+ */
+export declare function streamPrompt(api: BoatApi, sandboxId: string, promptRequest: PromptRequest, options?: StreamPromptOptions): AsyncGenerator<SandboxEvent>;
+/**
+ * Stop a sandbox, or delete it outright.
+ *
+ * The default stops the sandbox and keeps its snapshots, so it can be resumed or
+ * forked later. `options.delete` is irreversible: the sandbox is force-stopped
+ * without a final snapshot and every snapshot chain only it uses is deleted.
+ *
+ * The generated method is `deleteSandbox`, not `delete` -- `delete` is a reserved
+ * word the generators rename, and calling a method the SDK does not actually
+ * expose is what broke the TypeScript build (TS2339) and stopped it publishing.
+ */
+export declare function stopAndRemove(api: BoatApi, sandboxId: string, options?: {
+    delete?: boolean;
+}): Promise<import("./models").DeletionOperationResponse | import("./models").SandboxActionResponse>;
+export declare function readText(api: BoatApi, sandboxId: string, path: string): Promise<string>;
+export declare function writeText(api: BoatApi, sandboxId: string, path: string, content: string): Promise<import("./models").FileWriteResponse>;
+export declare function execCommand(api: BoatApi, sandboxId: string, command: string, cwd?: string, timeoutSeconds?: number): Promise<import("./models").Command200Response>;

package/dist/boat-helpers.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitForPromptDone = void 0;
+exports.waitUntilReady = waitUntilReady;
+exports.waitUntilIdle = waitUntilIdle;
+exports.waitForDesktop = waitForDesktop;
+exports.waitForPrompt = waitForPrompt;
+exports.streamEvents = streamEvents;
+exports.streamPrompt = streamPrompt;
+exports.stopAndRemove = stopAndRemove;
+exports.readText = readText;
+exports.writeText = writeText;
+exports.execCommand = execCommand;
+const terminalPromptStatuses = new Set(['finished', 'failed']);
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function poll(options, fn) {
+    var _a, _b;
+    const timeoutMs = (_a = options === null || options === void 0 ? void 0 : options.timeoutMs) !== null && _a !== void 0 ? _a : 300000;
+    const intervalMs = (_b = options === null || options === void 0 ? void 0 : options.intervalMs) !== null && _b !== void 0 ? _b : 2000;
+    const deadline = timeoutMs === 0 ? Number.POSITIVE_INFINITY : Date.now() + timeoutMs;
+    for (;;) {
+        const value = await fn();
+        if (value !== undefined)
+            return value;
+        if (Date.now() >= deadline)
+            throw new Error('Timed out waiting for sandbox state');
+        await delay(intervalMs);
+    }
+}
+async function waitUntilReady(api, sandboxId, options) {
+    return poll(options, async () => {
+        const sandbox = (await api.get({ sandboxId })).sandbox;
+        if (['ready', 'idle', 'running'].indexOf(sandbox.state) !== -1)
+            return sandbox;
+        if (['archived', 'archiving', 'error'].indexOf(sandbox.state) !== -1)
+            throw new Error(`Sandbox entered terminal state ${sandbox.state}`);
+        return undefined;
+    });
+}
+async function waitUntilIdle(api, sandboxId, options) {
+    return poll({ timeoutMs: 600000, intervalMs: 2000, ...options }, async () => {
+        const sandbox = (await api.get({ sandboxId })).sandbox;
+        if (sandbox.state === 'idle')
+            return sandbox;
+        if (['archived', 'archiving', 'error'].indexOf(sandbox.state) !== -1)
+            throw new Error(`Sandbox entered terminal state ${sandbox.state}`);
+        return undefined;
+    });
+}
+async function waitForDesktop(api, sandboxId, options) {
+    return poll(options, async () => {
+        var _a;
+        const desktopRequest = (options === null || options === void 0 ? void 0 : options.publicAccess) ? { publicAccess: true } : {};
+        const desktop = await api.desktop({ sandboxId, vnc: ((_a = options === null || options === void 0 ? void 0 : options.vnc) !== null && _a !== void 0 ? _a : 1), desktopRequest });
+        return desktop.desktopUrl && !desktop.provisioning ? desktop : undefined;
+    });
+}
+async function waitForPrompt(api, sandboxId, promptId, options) {
+    return poll({ timeoutMs: 1800000, intervalMs: 2000, ...options }, async () => {
+        const run = (await api.promptRunStatus({ sandboxId, promptId })).promptRun;
+        return terminalPromptStatuses.has(run.status) ? run : undefined;
+    });
+}
+exports.waitForPromptDone = waitForPrompt;
+function encodeCursor(event) {
+    const raw = `${event.timestamp}:${event.id}`;
+    const bufferCtor = globalThis.Buffer;
+    if (bufferCtor)
+        return bufferCtor.from(raw, 'utf8').toString('base64url');
+    return btoa(raw).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+function eventStatus(event) {
+    const data = event.data;
+    return typeof (data === null || data === void 0 ? void 0 : data.status) === 'string' ? data.status : undefined;
+}
+function throwIfAborted(signal) {
+    if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+        throw new Error('Sandbox event stream aborted');
+}
+/**
+ * Long-poll sandbox events and yield each new event once.
+ *
+ * The v1 API does not require a separate SSE/WebSocket connection. This helper
+ * polls `events({ sort: "asc" })`, advances a cursor after every event, and
+ * yields response events as soon as they are persisted. Streaming response
+ * partials have `event.data.isStreaming === true` (or `is_streaming` in raw
+ * JSON); tool-call events are response events whose `event.data.tools` array is
+ * present.
+ */
+async function* streamEvents(api, sandboxId, options) {
+    var _a, _b, _c, _d, _e;
+    const limit = (_a = options === null || options === void 0 ? void 0 : options.limit) !== null && _a !== void 0 ? _a : 100;
+    const intervalMs = (_b = options === null || options === void 0 ? void 0 : options.intervalMs) !== null && _b !== void 0 ? _b : 1000;
+    const timeoutMs = (_c = options === null || options === void 0 ? void 0 : options.timeoutMs) !== null && _c !== void 0 ? _c : 0;
+    const deadline = timeoutMs === 0 ? Number.POSITIVE_INFINITY : Date.now() + timeoutMs;
+    let cursor;
+    if (!(options === null || options === void 0 ? void 0 : options.includeExisting)) {
+        const existing = (_d = (await api.events({ sandboxId, limit: 200, sort: 'asc', type: options === null || options === void 0 ? void 0 : options.type })).events) !== null && _d !== void 0 ? _d : [];
+        const last = existing[existing.length - 1];
+        if ((last === null || last === void 0 ? void 0 : last.id) && (last === null || last === void 0 ? void 0 : last.timestamp))
+            cursor = encodeCursor(last);
+    }
+    for (;;) {
+        throwIfAborted(options === null || options === void 0 ? void 0 : options.signal);
+        const page = await api.events({ sandboxId, limit, cursor, sort: 'asc', type: options === null || options === void 0 ? void 0 : options.type });
+        for (const event of (_e = page.events) !== null && _e !== void 0 ? _e : []) {
+            cursor = encodeCursor(event);
+            yield event;
+        }
+        if (Date.now() >= deadline)
+            throw new Error('Timed out streaming sandbox events');
+        await delay(intervalMs);
+    }
+}
+/**
+ * Queue a prompt, then yield its prompt/response/tool events until the prompt
+ * reaches `finished` or `failed`.
+ */
+async function* streamPrompt(api, sandboxId, promptRequest, options) {
+    var _a, _b, _c, _d, _e;
+    const existing = (_a = (await api.events({ sandboxId, limit: 200, sort: 'asc' })).events) !== null && _a !== void 0 ? _a : [];
+    let cursor;
+    const last = existing[existing.length - 1];
+    if ((last === null || last === void 0 ? void 0 : last.id) && (last === null || last === void 0 ? void 0 : last.timestamp))
+        cursor = encodeCursor(last);
+    const response = await api.prompt({ sandboxId, promptRequest });
+    const promptId = response.promptId;
+    const intervalMs = (_b = options === null || options === void 0 ? void 0 : options.intervalMs) !== null && _b !== void 0 ? _b : 1000;
+    const timeoutMs = (_c = options === null || options === void 0 ? void 0 : options.timeoutMs) !== null && _c !== void 0 ? _c : 1800000;
+    const deadline = timeoutMs === 0 ? Number.POSITIVE_INFINITY : Date.now() + timeoutMs;
+    for (;;) {
+        throwIfAborted(options === null || options === void 0 ? void 0 : options.signal);
+        const page = await api.events({ sandboxId, limit: 100, cursor, sort: 'asc', type: 'prompt,response,usage_limit,shield' });
+        for (const event of (_d = page.events) !== null && _d !== void 0 ? _d : []) {
+            cursor = encodeCursor(event);
+            if (event.taskId !== promptId)
+                continue;
+            yield event;
+            if (event.type === 'prompt' && terminalPromptStatuses.has((_e = eventStatus(event)) !== null && _e !== void 0 ? _e : ''))
+                return;
+        }
+        const run = (await api.promptRunStatus({ sandboxId, promptId })).promptRun;
+        if (terminalPromptStatuses.has(run.status))
+            return;
+        if (Date.now() >= deadline)
+            throw new Error('Timed out streaming prompt events');
+        await delay(intervalMs);
+    }
+}
+/**
+ * Stop a sandbox, or delete it outright.
+ *
+ * The default stops the sandbox and keeps its snapshots, so it can be resumed or
+ * forked later. `options.delete` is irreversible: the sandbox is force-stopped
+ * without a final snapshot and every snapshot chain only it uses is deleted.
+ *
+ * The generated method is `deleteSandbox`, not `delete` -- `delete` is a reserved
+ * word the generators rename, and calling a method the SDK does not actually
+ * expose is what broke the TypeScript build (TS2339) and stopped it publishing.
+ */
+async function stopAndRemove(api, sandboxId, options) {
+    if (options === null || options === void 0 ? void 0 : options.delete)
+        return api.deleteSandbox({ sandboxId, xAsciiConfirmDelete: sandboxId });
+    return api.stop({ sandboxId });
+}
+async function readText(api, sandboxId, path) {
+    return (await api.readFile({ sandboxId, path, encoding: 'utf8' })).content;
+}
+async function writeText(api, sandboxId, path, content) {
+    return api.writeFile({ sandboxId, fileWriteRequest: { path, content, encoding: 'utf8' } });
+}
+async function execCommand(api, sandboxId, command, cwd, timeoutSeconds = 30) {
+    return api.command({ sandboxId, commandRequest: { command, cwd, timeoutSeconds } });
+}