@opencomputer/sdk 0.4.0

package/README.md

@@ -0,0 +1,39 @@
+# @opencomputer/sdk
+
+TypeScript SDK for [OpenComputer](https://github.com/diggerhq/opensandbox) — cloud sandbox platform.
+
+## Install
+
+```bash
+npm install @opencomputer/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Sandbox } from "@opencomputer/sdk";
+
+const sandbox = await Sandbox.create({ template: "base" });
+
+// Execute commands
+const result = await sandbox.commands.run("echo hello");
+console.log(result.stdout); // "hello\n"
+
+// Read and write files
+await sandbox.files.write("/tmp/test.txt", "Hello, world!");
+const content = await sandbox.files.read("/tmp/test.txt");
+
+// Clean up
+await sandbox.kill();
+```
+
+## Configuration
+
+| Option    | Env Variable            | Default                  |
+|-----------|------------------------|--------------------------|
+| `apiUrl`  | `OPENSANDBOX_API_URL`  | `https://app.opencomputer.dev`  |
+| `apiKey`  | `OPENSANDBOX_API_KEY`  | (none)                   |
+
+## License
+
+MIT

package/dist/commands.d.ts

@@ -0,0 +1,19 @@
+export interface ProcessResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface RunOpts {
+    timeout?: number;
+    env?: Record<string, string>;
+    cwd?: string;
+}
+export declare class Commands {
+    private apiUrl;
+    private apiKey;
+    private sandboxId;
+    private token;
+    constructor(apiUrl: string, apiKey: string, sandboxId: string, token?: string);
+    private get headers();
+    run(command: string, opts?: RunOpts): Promise<ProcessResult>;
+}

package/dist/commands.js

@@ -0,0 +1,51 @@
+export class Commands {
+    apiUrl;
+    apiKey;
+    sandboxId;
+    token;
+    constructor(apiUrl, apiKey, sandboxId, token = "") {
+        this.apiUrl = apiUrl;
+        this.apiKey = apiKey;
+        this.sandboxId = sandboxId;
+        this.token = token;
+    }
+    get headers() {
+        const h = { "Content-Type": "application/json" };
+        if (this.token) {
+            h["Authorization"] = `Bearer ${this.token}`;
+        }
+        else if (this.apiKey) {
+            h["X-API-Key"] = this.apiKey;
+        }
+        return h;
+    }
+    async run(command, opts = {}) {
+        const timeout = opts.timeout ?? 60;
+        const body = {
+            cmd: command,
+            timeout,
+        };
+        if (opts.env)
+            body.envs = opts.env;
+        if (opts.cwd)
+            body.cwd = opts.cwd;
+        const controller = new AbortController();
+        const timeoutId = globalThis.setTimeout(() => controller.abort(), (timeout + 5) * 1000);
+        try {
+            const resp = await fetch(`${this.apiUrl}/sandboxes/${this.sandboxId}/commands`, {
+                method: "POST",
+                headers: this.headers,
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!resp.ok) {
+                const text = await resp.text();
+                throw new Error(`Command failed: ${resp.status} ${text}`);
+            }
+            return await resp.json();
+        }
+        finally {
+            globalThis.clearTimeout(timeoutId);
+        }
+    }
+}

package/dist/filesystem.d.ts

@@ -0,0 +1,21 @@
+export interface EntryInfo {
+    name: string;
+    isDir: boolean;
+    path: string;
+    size: number;
+}
+export declare class Filesystem {
+    private apiUrl;
+    private apiKey;
+    private sandboxId;
+    private token;
+    constructor(apiUrl: string, apiKey: string, sandboxId: string, token?: string);
+    private get headers();
+    read(path: string): Promise<string>;
+    readBytes(path: string): Promise<Uint8Array>;
+    write(path: string, content: string | Uint8Array): Promise<void>;
+    list(path?: string): Promise<EntryInfo[]>;
+    makeDir(path: string): Promise<void>;
+    remove(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+}

package/dist/filesystem.js

@@ -0,0 +1,64 @@
+export class Filesystem {
+    apiUrl;
+    apiKey;
+    sandboxId;
+    token;
+    constructor(apiUrl, apiKey, sandboxId, token = "") {
+        this.apiUrl = apiUrl;
+        this.apiKey = apiKey;
+        this.sandboxId = sandboxId;
+        this.token = token;
+    }
+    get headers() {
+        if (this.token)
+            return { "Authorization": `Bearer ${this.token}` };
+        return this.apiKey ? { "X-API-Key": this.apiKey } : {};
+    }
+    async read(path) {
+        const resp = await fetch(`${this.apiUrl}/sandboxes/${this.sandboxId}/files?path=${encodeURIComponent(path)}`, { headers: this.headers });
+        if (!resp.ok)
+            throw new Error(`Failed to read ${path}: ${resp.status}`);
+        return resp.text();
+    }
+    async readBytes(path) {
+        const resp = await fetch(`${this.apiUrl}/sandboxes/${this.sandboxId}/files?path=${encodeURIComponent(path)}`, { headers: this.headers });
+        if (!resp.ok)
+            throw new Error(`Failed to read ${path}: ${resp.status}`);
+        return new Uint8Array(await resp.arrayBuffer());
+    }
+    async write(path, content) {
+        const resp = await fetch(`${this.apiUrl}/sandboxes/${this.sandboxId}/files?path=${encodeURIComponent(path)}`, {
+            method: "PUT",
+            headers: this.headers,
+            body: content,
+        });
+        if (!resp.ok)
+            throw new Error(`Failed to write ${path}: ${resp.status}`);
+    }
+    async list(path = "/") {
+        const resp = await fetch(`${this.apiUrl}/sandboxes/${this.sandboxId}/files/list?path=${encodeURIComponent(path)}`, { headers: this.headers });
+        if (!resp.ok)
+            throw new Error(`Failed to list ${path}: ${resp.status}`);
+        const data = await resp.json();
+        return data ?? [];
+    }
+    async makeDir(path) {
+        const resp = await fetch(`${this.apiUrl}/sandboxes/${this.sandboxId}/files/mkdir?path=${encodeURIComponent(path)}`, { method: "POST", headers: this.headers });
+        if (!resp.ok)
+            throw new Error(`Failed to mkdir ${path}: ${resp.status}`);
+    }
+    async remove(path) {
+        const resp = await fetch(`${this.apiUrl}/sandboxes/${this.sandboxId}/files?path=${encodeURIComponent(path)}`, { method: "DELETE", headers: this.headers });
+        if (!resp.ok)
+            throw new Error(`Failed to remove ${path}: ${resp.status}`);
+    }
+    async exists(path) {
+        try {
+            const resp = await fetch(`${this.apiUrl}/sandboxes/${this.sandboxId}/files?path=${encodeURIComponent(path)}`, { headers: this.headers });
+            return resp.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Sandbox, type SandboxOpts } from "./sandbox";
+export { Filesystem, type EntryInfo } from "./filesystem";
+export { Commands, type ProcessResult, type RunOpts } from "./commands";
+export { Pty, type PtySession, type PtyOpts } from "./pty";
+export { Templates, type TemplateInfo } from "./template";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { Sandbox } from "./sandbox";
+export { Filesystem } from "./filesystem";
+export { Commands } from "./commands";
+export { Pty } from "./pty";
+export { Templates } from "./template";

package/dist/pty.d.ts

@@ -0,0 +1,19 @@
+export interface PtyOpts {
+    cols?: number;
+    rows?: number;
+    onOutput?: (data: Uint8Array) => void;
+}
+export interface PtySession {
+    sessionId: string;
+    send(data: string | Uint8Array): void;
+    close(): void;
+}
+export declare class Pty {
+    private apiUrl;
+    private apiKey;
+    private sandboxId;
+    private token;
+    constructor(apiUrl: string, apiKey: string, sandboxId: string, token?: string);
+    private get headers();
+    create(opts?: PtyOpts): Promise<PtySession>;
+}

package/dist/pty.js

@@ -0,0 +1,68 @@
+export class Pty {
+    apiUrl;
+    apiKey;
+    sandboxId;
+    token;
+    constructor(apiUrl, apiKey, sandboxId, token = "") {
+        this.apiUrl = apiUrl;
+        this.apiKey = apiKey;
+        this.sandboxId = sandboxId;
+        this.token = token;
+    }
+    get headers() {
+        const h = { "Content-Type": "application/json" };
+        if (this.token) {
+            h["Authorization"] = `Bearer ${this.token}`;
+        }
+        else if (this.apiKey) {
+            h["X-API-Key"] = this.apiKey;
+        }
+        return h;
+    }
+    async create(opts = {}) {
+        // Create session via REST
+        const resp = await fetch(`${this.apiUrl}/sandboxes/${this.sandboxId}/pty`, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify({
+                cols: opts.cols ?? 80,
+                rows: opts.rows ?? 24,
+            }),
+        });
+        if (!resp.ok) {
+            throw new Error(`Failed to create PTY: ${resp.status}`);
+        }
+        const data = await resp.json();
+        const sessionId = data.sessionID;
+        // Connect via WebSocket
+        const wsUrl = this.apiUrl
+            .replace("http://", "ws://")
+            .replace("https://", "wss://");
+        const wsEndpoint = `${wsUrl}/sandboxes/${this.sandboxId}/pty/${sessionId}`;
+        const ws = new WebSocket(wsEndpoint);
+        ws.binaryType = "arraybuffer";
+        if (opts.onOutput) {
+            const onOutput = opts.onOutput;
+            ws.onmessage = (event) => {
+                const data = event.data instanceof ArrayBuffer
+                    ? new Uint8Array(event.data)
+                    : new TextEncoder().encode(event.data);
+                onOutput(data);
+            };
+        }
+        return {
+            sessionId,
+            send(data) {
+                if (typeof data === "string") {
+                    ws.send(data);
+                }
+                else {
+                    ws.send(data);
+                }
+            },
+            close() {
+                ws.close();
+            },
+        };
+    }
+}

package/dist/sandbox.d.ts

@@ -0,0 +1,34 @@
+import { Filesystem } from "./filesystem";
+import { Commands } from "./commands";
+import { Pty } from "./pty";
+export interface SandboxOpts {
+    template?: string;
+    timeout?: number;
+    apiKey?: string;
+    apiUrl?: string;
+    envs?: Record<string, string>;
+    metadata?: Record<string, string>;
+}
+export declare class Sandbox {
+    readonly sandboxId: string;
+    readonly domain: string;
+    readonly files: Filesystem;
+    readonly commands: Commands;
+    readonly pty: Pty;
+    private apiUrl;
+    private apiKey;
+    private connectUrl;
+    private token;
+    private _status;
+    private constructor();
+    get status(): string;
+    static create(opts?: SandboxOpts): Promise<Sandbox>;
+    static connect(sandboxId: string, opts?: Pick<SandboxOpts, "apiKey" | "apiUrl">): Promise<Sandbox>;
+    kill(): Promise<void>;
+    isRunning(): Promise<boolean>;
+    hibernate(): Promise<void>;
+    wake(opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    setTimeout(timeout: number): Promise<void>;
+}

package/dist/sandbox.js

@@ -0,0 +1,153 @@
+import { Filesystem } from "./filesystem";
+import { Commands } from "./commands";
+import { Pty } from "./pty";
+function resolveApiUrl(url) {
+    const base = url.replace(/\/+$/, "");
+    return base.endsWith("/api") ? base : `${base}/api`;
+}
+export class Sandbox {
+    sandboxId;
+    domain;
+    files;
+    commands;
+    pty;
+    apiUrl;
+    apiKey;
+    connectUrl;
+    token;
+    _status;
+    constructor(data, apiUrl, apiKey) {
+        this.sandboxId = data.sandboxID;
+        this.domain = data.domain || "";
+        this._status = data.status;
+        this.apiUrl = apiUrl;
+        this.apiKey = apiKey;
+        this.connectUrl = data.connectURL || "";
+        this.token = data.token || "";
+        // Use direct worker URL for data operations if available
+        const opsUrl = this.connectUrl || apiUrl;
+        const opsKey = this.connectUrl ? "" : apiKey;
+        const opsToken = this.connectUrl ? this.token : "";
+        this.files = new Filesystem(opsUrl, opsKey, this.sandboxId, opsToken);
+        this.commands = new Commands(opsUrl, opsKey, this.sandboxId, opsToken);
+        this.pty = new Pty(opsUrl, opsKey, this.sandboxId, opsToken);
+    }
+    get status() {
+        return this._status;
+    }
+    static async create(opts = {}) {
+        const apiUrl = resolveApiUrl(opts.apiUrl ?? process.env.OPENSANDBOX_API_URL ?? "https://app.opencomputer.dev");
+        const apiKey = opts.apiKey ?? process.env.OPENSANDBOX_API_KEY ?? "";
+        const body = {
+            templateID: opts.template ?? "base",
+            timeout: opts.timeout ?? 300,
+        };
+        if (opts.envs)
+            body.envs = opts.envs;
+        if (opts.metadata)
+            body.metadata = opts.metadata;
+        const resp = await fetch(`${apiUrl}/sandboxes`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...(apiKey ? { "X-API-Key": apiKey } : {}),
+            },
+            body: JSON.stringify(body),
+        });
+        if (!resp.ok) {
+            const text = await resp.text();
+            throw new Error(`Failed to create sandbox: ${resp.status} ${text}`);
+        }
+        const data = await resp.json();
+        return new Sandbox(data, apiUrl, apiKey);
+    }
+    static async connect(sandboxId, opts = {}) {
+        const apiUrl = resolveApiUrl(opts.apiUrl ?? process.env.OPENSANDBOX_API_URL ?? "https://app.opencomputer.dev");
+        const apiKey = opts.apiKey ?? process.env.OPENSANDBOX_API_KEY ?? "";
+        const resp = await fetch(`${apiUrl}/sandboxes/${sandboxId}`, {
+            headers: apiKey ? { "X-API-Key": apiKey } : {},
+        });
+        if (!resp.ok) {
+            throw new Error(`Failed to connect to sandbox ${sandboxId}: ${resp.status}`);
+        }
+        const data = await resp.json();
+        return new Sandbox(data, apiUrl, apiKey);
+    }
+    async kill() {
+        const resp = await fetch(`${this.apiUrl}/sandboxes/${this.sandboxId}`, {
+            method: "DELETE",
+            headers: this.apiKey ? { "X-API-Key": this.apiKey } : {},
+        });
+        if (!resp.ok) {
+            throw new Error(`Failed to kill sandbox: ${resp.status}`);
+        }
+        this._status = "stopped";
+    }
+    async isRunning() {
+        try {
+            const resp = await fetch(`${this.apiUrl}/sandboxes/${this.sandboxId}`, {
+                headers: this.apiKey ? { "X-API-Key": this.apiKey } : {},
+            });
+            if (!resp.ok)
+                return false;
+            const data = await resp.json();
+            this._status = data.status;
+            return data.status === "running";
+        }
+        catch {
+            return false;
+        }
+    }
+    async hibernate() {
+        const resp = await fetch(`${this.apiUrl}/sandboxes/${this.sandboxId}/hibernate`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...(this.apiKey ? { "X-API-Key": this.apiKey } : {}),
+            },
+        });
+        if (!resp.ok) {
+            const text = await resp.text();
+            throw new Error(`Failed to hibernate sandbox: ${resp.status} ${text}`);
+        }
+        this._status = "hibernated";
+    }
+    async wake(opts = {}) {
+        const resp = await fetch(`${this.apiUrl}/sandboxes/${this.sandboxId}/wake`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...(this.apiKey ? { "X-API-Key": this.apiKey } : {}),
+            },
+            body: JSON.stringify({ timeout: opts.timeout ?? 300 }),
+        });
+        if (!resp.ok) {
+            const text = await resp.text();
+            throw new Error(`Failed to wake sandbox: ${resp.status} ${text}`);
+        }
+        const data = await resp.json();
+        this._status = data.status;
+        this.connectUrl = data.connectURL || "";
+        this.token = data.token || "";
+        // Rebuild ops clients with new worker connection
+        const opsUrl = this.connectUrl || this.apiUrl;
+        const opsKey = this.connectUrl ? "" : this.apiKey;
+        const opsToken = this.connectUrl ? this.token : "";
+        this.files = new Filesystem(opsUrl, opsKey, this.sandboxId, opsToken);
+        this.commands = new Commands(opsUrl, opsKey, this.sandboxId, opsToken);
+        this.pty = new Pty(opsUrl, opsKey, this.sandboxId, opsToken);
+    }
+    async setTimeout(timeout) {
+        const resp = await fetch(`${this.apiUrl}/sandboxes/${this.sandboxId}/timeout`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...(this.apiKey ? { "X-API-Key": this.apiKey } : {}),
+            },
+            body: JSON.stringify({ timeout }),
+        });
+        if (!resp.ok) {
+            throw new Error(`Failed to set timeout: ${resp.status}`);
+        }
+    }
+}

package/dist/template.d.ts

@@ -0,0 +1,16 @@
+export interface TemplateInfo {
+    templateID: string;
+    name: string;
+    tag: string;
+    status: string;
+}
+export declare class Templates {
+    private apiUrl;
+    private apiKey;
+    constructor(apiUrl: string, apiKey: string);
+    private get headers();
+    build(name: string, dockerfile: string): Promise<TemplateInfo>;
+    list(): Promise<TemplateInfo[]>;
+    get(name: string): Promise<TemplateInfo>;
+    delete(name: string): Promise<void>;
+}

package/dist/template.js

@@ -0,0 +1,52 @@
+export class Templates {
+    apiUrl;
+    apiKey;
+    constructor(apiUrl, apiKey) {
+        this.apiUrl = apiUrl;
+        this.apiKey = apiKey;
+    }
+    get headers() {
+        const h = { "Content-Type": "application/json" };
+        if (this.apiKey)
+            h["X-API-Key"] = this.apiKey;
+        return h;
+    }
+    async build(name, dockerfile) {
+        const resp = await fetch(`${this.apiUrl}/templates`, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify({ name, dockerfile }),
+        });
+        if (!resp.ok) {
+            throw new Error(`Failed to build template: ${resp.status}`);
+        }
+        return resp.json();
+    }
+    async list() {
+        const resp = await fetch(`${this.apiUrl}/templates`, {
+            headers: this.headers,
+        });
+        if (!resp.ok) {
+            throw new Error(`Failed to list templates: ${resp.status}`);
+        }
+        return resp.json();
+    }
+    async get(name) {
+        const resp = await fetch(`${this.apiUrl}/templates/${name}`, {
+            headers: this.headers,
+        });
+        if (!resp.ok) {
+            throw new Error(`Failed to get template: ${resp.status}`);
+        }
+        return resp.json();
+    }
+    async delete(name) {
+        const resp = await fetch(`${this.apiUrl}/templates/${name}`, {
+            method: "DELETE",
+            headers: this.headers,
+        });
+        if (!resp.ok) {
+            throw new Error(`Failed to delete template: ${resp.status}`);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@opencomputer/sdk",
+  "version": "0.4.0",
+  "description": "TypeScript SDK for OpenComputer - cloud sandbox platform",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "sandbox",
+    "opencomputer",
+    "e2b",
+    "cloud",
+    "containers",
+    "code-execution"
+  ],
+  "author": "OpenComputer",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/diggerhq/opensandbox.git",
+    "directory": "sdks/typescript"
+  },
+  "homepage": "https://github.com/diggerhq/opensandbox/tree/main/sdks/typescript",
+  "bugs": {
+    "url": "https://github.com/diggerhq/opensandbox/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}