sandbox0 0.1.0

package/dist/sandbox_files.js

@@ -0,0 +1,148 @@
+import { models } from "./apispec_compat";
+import { APIError, wrapApiCall } from "./errors";
+import { ensureData, ensureModel } from "./response";
+import { FileWatchStream, Sandbox } from "./sandbox";
+import { WebSocketClient } from "./ws_client";
+function getClient(sandbox) {
+    return sandbox.client;
+}
+Sandbox.prototype.readFile = async function (path) {
+    const client = getClient(this);
+    const response = await wrapApiCall(() => client.apispec.files.apiV1SandboxesIdFilesGetRaw({
+        id: this.id,
+        path,
+    }));
+    const contentType = response.raw.headers.get("content-type")?.toLowerCase() ?? "";
+    if (contentType.includes("application/json")) {
+        const payload = (await response.raw.json());
+        const data = ensureData(payload, "read file returned empty response");
+        const content = data.content ?? "";
+        const encoding = data.encoding;
+        if (encoding && encoding !== models.FileContentResponseEncodingEnum.Base64) {
+            throw new APIError({
+                statusCode: response.raw.status,
+                code: "unsupported_encoding",
+                message: `unsupported file encoding: ${encoding}`,
+            });
+        }
+        return Buffer.from(content, "base64");
+    }
+    const blob = await response.value();
+    const buffer = await blob.arrayBuffer();
+    return new Uint8Array(buffer);
+};
+Sandbox.prototype.statFile = async function (path) {
+    const client = getClient(this);
+    const response = await wrapApiCall(() => client.apispec.files.apiV1SandboxesIdFilesStatGet({
+        id: this.id,
+        path,
+    }));
+    return ensureData(response, "stat file returned empty response");
+};
+Sandbox.prototype.listFiles = async function (path) {
+    const client = getClient(this);
+    const response = await wrapApiCall(() => client.apispec.files.apiV1SandboxesIdFilesListGet({
+        id: this.id,
+        path,
+    }));
+    const data = ensureData(response, "list files returned empty response");
+    return data.entries ?? [];
+};
+Sandbox.prototype.writeFile = async function (path, data) {
+    const client = getClient(this);
+    const payload = typeof data === "string" ? Buffer.from(data) : data;
+    const response = await wrapApiCall(() => client.apispec.files.apiV1SandboxesIdFilesPost({
+        id: this.id,
+        path,
+        body: new Blob([payload]),
+    }));
+    return ensureModel(response, "write file returned empty response");
+};
+Sandbox.prototype.mkdir = async function (path, recursive = false) {
+    const client = getClient(this);
+    const response = await wrapApiCall(() => client.apispec.files.apiV1SandboxesIdFilesPost({
+        id: this.id,
+        path,
+        mkdir: true,
+        recursive: recursive || undefined,
+        body: new Blob([]),
+    }));
+    return ensureModel(response, "mkdir returned empty response");
+};
+Sandbox.prototype.deleteFile = async function (path) {
+    const client = getClient(this);
+    const response = await wrapApiCall(() => client.apispec.files.apiV1SandboxesIdFilesDelete({
+        id: this.id,
+        path,
+    }));
+    return ensureModel(response, "delete file returned empty response");
+};
+Sandbox.prototype.moveFile = async function (source, destination) {
+    const client = getClient(this);
+    const response = await wrapApiCall(() => client.apispec.files.apiV1SandboxesIdFilesMovePost({
+        id: this.id,
+        moveFileRequest: { source, destination },
+    }));
+    return ensureModel(response, "move file returned empty response");
+};
+Sandbox.prototype.watchFiles = async function (path, recursive = false) {
+    const client = getClient(this);
+    const wsUrl = client.websocketUrl(`/api/v1/sandboxes/${this.id}/files/watch`);
+    const headers = await client.wsHeaders();
+    const socket = new WebSocketClient(wsUrl, { headers });
+    await socket.waitForOpen();
+    socket.send(JSON.stringify({ action: "subscribe", path, recursive: !!recursive }));
+    const firstRaw = await socket.waitForMessage();
+    const first = firstRaw ? parseWsMessage(firstRaw) : null;
+    if (!first) {
+        socket.close();
+        throw new APIError({
+            statusCode: 0,
+            code: "watch_failed",
+            message: "watch subscribe failed: empty response",
+        });
+    }
+    if (first.type === "error") {
+        socket.close();
+        throw new APIError({
+            statusCode: 0,
+            code: "watch_failed",
+            message: `watch subscribe failed: ${first.error ?? ""}`,
+        });
+    }
+    if (first.type !== "subscribed" || !first.watch_id) {
+        socket.close();
+        throw new APIError({
+            statusCode: 0,
+            code: "watch_failed",
+            message: `unexpected watch response: ${first.type ?? ""}`,
+        });
+    }
+    const stream = new FileWatchStream(socket);
+    stream.watchId = String(first.watch_id);
+    return stream;
+};
+function parseWsMessage(data) {
+    try {
+        let text;
+        if (typeof data === "string") {
+            text = data;
+        }
+        else if (Buffer.isBuffer(data)) {
+            text = data.toString("utf-8");
+        }
+        else if (Array.isArray(data)) {
+            text = Buffer.concat(data).toString("utf-8");
+        }
+        else if (data instanceof ArrayBuffer) {
+            text = Buffer.from(data).toString("utf-8");
+        }
+        else {
+            text = Buffer.from(data).toString("utf-8");
+        }
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/sandbox_network.d.ts

@@ -0,0 +1,8 @@
+import type { TplSandboxNetworkPolicy } from "./apispec/src/models/index";
+declare module "./sandbox" {
+    interface Sandbox {
+        getNetworkPolicy(): Promise<TplSandboxNetworkPolicy>;
+        updateNetworkPolicy(policy: TplSandboxNetworkPolicy): Promise<TplSandboxNetworkPolicy>;
+    }
+}
+//# sourceMappingURL=sandbox_network.d.ts.map

package/dist/sandbox_network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox_network.d.ts","sourceRoot":"","sources":["../src/sandbox_network.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAU1E,OAAO,QAAQ,WAAW,CAAC;IACzB,UAAU,OAAO;QACf,gBAAgB,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAAC;QACrD,mBAAmB,CACjB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,uBAAuB,CAAC,CAAC;KACrC;CACF"}

package/dist/sandbox_network.js

@@ -0,0 +1,19 @@
+import { wrapApiCall } from "./errors";
+import { ensureData } from "./response";
+import { Sandbox } from "./sandbox";
+function getClient(sandbox) {
+    return sandbox.client;
+}
+Sandbox.prototype.getNetworkPolicy = async function () {
+    const client = getClient(this);
+    const response = await wrapApiCall(() => client.apispec.sandboxes.apiV1SandboxesIdNetworkGet({ id: this.id }));
+    return ensureData(response, "get network policy returned empty response");
+};
+Sandbox.prototype.updateNetworkPolicy = async function (policy) {
+    const client = getClient(this);
+    const response = await wrapApiCall(() => client.apispec.sandboxes.apiV1SandboxesIdNetworkPut({
+        id: this.id,
+        tplSandboxNetworkPolicy: policy,
+    }));
+    return ensureData(response, "update network policy returned empty response");
+};

package/dist/sandbox_volumes.d.ts

@@ -0,0 +1,10 @@
+import type { MountRequest, MountStatus, SuccessUnmountedResponse } from "./apispec/src/models/index";
+import { MountSession } from "./sessions";
+declare module "./sandbox" {
+    interface Sandbox {
+        mount(volumeId: string, mountPoint: string, config?: MountRequest["volumeConfig"]): Promise<MountSession>;
+        unmount(volumeId: string, mountSessionId: string): Promise<SuccessUnmountedResponse>;
+        mountStatus(): Promise<MountStatus[]>;
+    }
+}
+//# sourceMappingURL=sandbox_volumes.d.ts.map

package/dist/sandbox_volumes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox_volumes.d.ts","sourceRoot":"","sources":["../src/sandbox_volumes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,wBAAwB,EACzB,MAAM,4BAA4B,CAAC;AAIpC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAO1C,OAAO,QAAQ,WAAW,CAAC;IACzB,UAAU,OAAO;QACf,KAAK,CACH,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,YAAY,CAAC,cAAc,CAAC,GACpC,OAAO,CAAC,YAAY,CAAC,CAAC;QACzB,OAAO,CACL,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,wBAAwB,CAAC,CAAC;QACrC,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;KACvC;CACF"}

package/dist/sandbox_volumes.js

@@ -0,0 +1,42 @@
+import { wrapApiCall } from "./errors";
+import { ensureData, ensureModel } from "./response";
+import { MountSession } from "./sessions";
+import { Sandbox } from "./sandbox";
+function getClient(sandbox) {
+    return sandbox.client;
+}
+Sandbox.prototype.mount = async function (volumeId, mountPoint, config) {
+    const client = getClient(this);
+    const request = {
+        sandboxvolumeId: volumeId,
+        mountPoint,
+        volumeConfig: config,
+    };
+    const response = await wrapApiCall(() => client.apispec.sandboxVolumes.apiV1SandboxesIdSandboxvolumesMountPost({
+        id: this.id,
+        mountRequest: request,
+    }));
+    const data = ensureData(response, "mount volume returned empty response");
+    return new MountSession(volumeId, data.mountPoint, data.mountSessionId, async () => {
+        await this.unmount(volumeId, data.mountSessionId);
+    });
+};
+Sandbox.prototype.unmount = async function (volumeId, mountSessionId) {
+    const client = getClient(this);
+    const response = await wrapApiCall(() => client.apispec.sandboxVolumes.apiV1SandboxesIdSandboxvolumesUnmountPost({
+        id: this.id,
+        unmountRequest: {
+            sandboxvolumeId: volumeId,
+            mountSessionId,
+        },
+    }));
+    return ensureModel(response, "unmount volume returned empty response");
+};
+Sandbox.prototype.mountStatus = async function () {
+    const client = getClient(this);
+    const response = await wrapApiCall(() => client.apispec.sandboxVolumes.apiV1SandboxesIdSandboxvolumesStatusGet({
+        id: this.id,
+    }));
+    const data = ensureData(response, "mount status returned empty response");
+    return data.mounts ?? [];
+};

package/dist/sessions.d.ts

@@ -0,0 +1,32 @@
+export declare class SandboxSession {
+    readonly sandbox: {
+        id: string;
+    };
+    private readonly closer;
+    private closed;
+    constructor(sandbox: {
+        id: string;
+    }, closer: () => Promise<void>);
+    close(): Promise<void>;
+}
+export declare class VolumeSession {
+    readonly volume: {
+        id: string;
+    };
+    private readonly closer;
+    private closed;
+    constructor(volume: {
+        id: string;
+    }, closer: () => Promise<void>);
+    close(): Promise<void>;
+}
+export declare class MountSession {
+    readonly volumeId: string;
+    readonly mountPoint: string;
+    readonly mountSessionId: string;
+    private readonly unmount;
+    private closed;
+    constructor(volumeId: string, mountPoint: string, mountSessionId: string, unmount: () => Promise<void>);
+    close(): Promise<void>;
+}
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"AAAA,qBAAa,cAAc;aAIP,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,OAAO,CAAC,MAAM,CAAS;gBAGL,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EACtB,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAGxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B;AAED,qBAAa,aAAa;aAIN,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,OAAO,CAAC,MAAM,CAAS;gBAGL,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EACrB,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAGxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B;AAED,qBAAa,YAAY;aAIL,QAAQ,EAAE,MAAM;aAChB,UAAU,EAAE,MAAM;aAClB,cAAc,EAAE,MAAM;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,MAAM,CAAS;gBAGL,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAGzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}

package/dist/sessions.js

@@ -0,0 +1,52 @@
+export class SandboxSession {
+    sandbox;
+    closer;
+    closed = false;
+    constructor(sandbox, closer) {
+        this.sandbox = sandbox;
+        this.closer = closer;
+    }
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        await this.closer();
+    }
+}
+export class VolumeSession {
+    volume;
+    closer;
+    closed = false;
+    constructor(volume, closer) {
+        this.volume = volume;
+        this.closer = closer;
+    }
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        await this.closer();
+    }
+}
+export class MountSession {
+    volumeId;
+    mountPoint;
+    mountSessionId;
+    unmount;
+    closed = false;
+    constructor(volumeId, mountPoint, mountSessionId, unmount) {
+        this.volumeId = volumeId;
+        this.mountPoint = mountPoint;
+        this.mountSessionId = mountSessionId;
+        this.unmount = unmount;
+    }
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        await this.unmount();
+    }
+}

package/dist/ws_client.d.ts

@@ -0,0 +1,24 @@
+import WebSocket from "ws";
+export type WebSocketRawData = WebSocket.RawData;
+type WebSocketClientOptions = {
+    headers?: Record<string, string>;
+    connectTimeoutMs?: number;
+};
+export declare class WebSocketClient {
+    private readonly socket;
+    private readonly pendingSends;
+    private closePending;
+    private readonly connectTimeoutMs;
+    constructor(url: string, options?: WebSocketClientOptions);
+    get readyState(): number;
+    waitForOpen(timeoutMs?: number): Promise<void>;
+    onMessage(handler: (data: WebSocketRawData) => void): () => void;
+    onClose(handler: () => void): () => void;
+    onError(handler: (err: Error) => void): () => void;
+    send(payload: string): void;
+    close(): void;
+    waitForMessage(timeoutMs?: number): Promise<WebSocketRawData | null>;
+    private flushPendingSends;
+}
+export {};
+//# sourceMappingURL=ws_client.d.ts.map

package/dist/ws_client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws_client.d.ts","sourceRoot":"","sources":["../src/ws_client.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,IAAI,CAAC;AAE3B,MAAM,MAAM,gBAAgB,GAAG,SAAS,CAAC,OAAO,CAAC;AAEjD,KAAK,sBAAsB,GAAG;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;IAC7C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B;IAa7D,IAAI,UAAU,IAAI,MAAM,CAEvB;IAEK,WAAW,CAAC,SAAS,SAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCnE,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI;IAKhE,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKxC,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI;IAKlD,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAY3B,KAAK,IAAI,IAAI;IAYP,cAAc,CAAC,SAAS,SAAQ,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAiCzE,OAAO,CAAC,iBAAiB;CAQ1B"}

package/dist/ws_client.js

@@ -0,0 +1,127 @@
+import WebSocket from "ws";
+export class WebSocketClient {
+    socket;
+    pendingSends = [];
+    closePending = false;
+    connectTimeoutMs;
+    constructor(url, options = {}) {
+        this.connectTimeoutMs = options.connectTimeoutMs ?? 10000;
+        this.socket = new WebSocket(url, { headers: options.headers });
+        this.socket.on("open", () => {
+            this.flushPendingSends();
+            if (this.closePending) {
+                this.closePending = false;
+                this.pendingSends.length = 0;
+                this.socket.close();
+            }
+        });
+    }
+    get readyState() {
+        return this.socket.readyState;
+    }
+    async waitForOpen(timeoutMs = this.connectTimeoutMs) {
+        if (this.socket.readyState === WebSocket.OPEN) {
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                cleanup();
+                this.socket.close();
+                reject(new Error("websocket open timeout"));
+            }, timeoutMs);
+            const onOpen = () => {
+                cleanup();
+                resolve();
+            };
+            const onError = (err) => {
+                cleanup();
+                reject(err instanceof Error ? err : new Error("websocket error"));
+            };
+            const onClose = () => {
+                cleanup();
+                reject(new Error("websocket closed before open"));
+            };
+            const cleanup = () => {
+                clearTimeout(timer);
+                this.socket.off("open", onOpen);
+                this.socket.off("error", onError);
+                this.socket.off("close", onClose);
+            };
+            this.socket.once("open", onOpen);
+            this.socket.once("error", onError);
+            this.socket.once("close", onClose);
+        });
+    }
+    onMessage(handler) {
+        this.socket.on("message", handler);
+        return () => this.socket.off("message", handler);
+    }
+    onClose(handler) {
+        this.socket.on("close", handler);
+        return () => this.socket.off("close", handler);
+    }
+    onError(handler) {
+        this.socket.on("error", handler);
+        return () => this.socket.off("error", handler);
+    }
+    send(payload) {
+        if (this.socket.readyState === WebSocket.OPEN) {
+            this.socket.send(payload);
+            return;
+        }
+        if (this.socket.readyState === WebSocket.CONNECTING) {
+            this.pendingSends.push(payload);
+            return;
+        }
+        throw new Error("websocket is not open");
+    }
+    close() {
+        this.pendingSends.length = 0;
+        if (this.socket.readyState === WebSocket.CONNECTING) {
+            this.closePending = true;
+            return;
+        }
+        if (this.socket.readyState === WebSocket.CLOSED) {
+            return;
+        }
+        this.socket.close();
+    }
+    async waitForMessage(timeoutMs = 10000) {
+        await this.waitForOpen();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                cleanup();
+                resolve(null);
+            }, timeoutMs);
+            const onMessage = (data) => {
+                cleanup();
+                resolve(data);
+            };
+            const onError = (err) => {
+                cleanup();
+                reject(err instanceof Error ? err : new Error("websocket error"));
+            };
+            const onClose = () => {
+                cleanup();
+                resolve(null);
+            };
+            const cleanup = () => {
+                clearTimeout(timer);
+                this.socket.off("message", onMessage);
+                this.socket.off("error", onError);
+                this.socket.off("close", onClose);
+            };
+            this.socket.once("message", onMessage);
+            this.socket.once("error", onError);
+            this.socket.once("close", onClose);
+        });
+    }
+    flushPendingSends() {
+        while (this.pendingSends.length > 0 && this.socket.readyState === WebSocket.OPEN) {
+            const payload = this.pendingSends.shift();
+            if (payload) {
+                this.socket.send(payload);
+            }
+        }
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "sandbox0",
+  "version": "0.1.0",
+  "description": "Sandbox0 JavaScript/TypeScript SDK",
+  "license": "Apache-2.0",
+  "author": "Sandbox0 Team",
+  "keywords": [
+    "sandbox",
+    "sdk",
+    "sandbox0"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "lint:examples": "tsc -p tsconfig.examples.json --noEmit",
+    "lint:e2e": "tsc -p tsconfig.e2e.json --noEmit",
+    "generate:apispec": "openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o src/apispec -c openapi-generator-config.yaml",
+    "test": "npx tsx tests/e2e/run.ts",
+    "test:e2e": "npx tsx tests/e2e/run.ts"
+  },
+  "devDependencies": {
+    "@openapitools/openapi-generator-cli": "^2.28.3",
+    "@types/node": "^25.2.3",
+    "@types/ws": "^8.18.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sandbox0-ai/sdk-js"
+  },
+  "dependencies": {
+    "shlex": "^3.0.0",
+    "ws": "^8.19.0"
+  }
+}