@sandbox-engine/sdk 0.1.4 → 0.2.0

package/dist/index.d.mts

@@ -30,11 +30,31 @@ interface SandboxOptions {
      */
     dockerfile?: string;
     timeout?: number;
+    /** Environment variables injected into the container for the entire session. */
+    env?: Record<string, string>;
 }
 interface SandboxConnectOptions {
     serverUrl?: string;
     apiKey?: string;
 }
+interface SandboxListOptions {
+    serverUrl?: string;
+    apiKey?: string;
+}
+interface SandboxSummary {
+    id: string;
+    status: string;
+    template: string;
+    createdAt: string;
+    timeout: number;
+    expiresAt: string | null;
+    agentUrl: string;
+    ports: Record<string, number>;
+}
+interface StreamLogsOptions {
+    onStdout?: (line: string) => void;
+    onStderr?: (line: string) => void;
+}
 interface StartProcessOptions {
     command?: string;
     cmd?: string;
@@ -92,6 +112,23 @@ interface FileWriteManyResult {
         error?: string;
     }>;
 }
+interface FileStat {
+    path: string;
+    size: number;
+    mtime: string;
+    isDirectory: boolean;
+    isFile: boolean;
+}
+interface FileWatchEvent {
+    type: 'change' | 'rename' | 'error';
+    eventType: 'create' | 'modify' | 'delete';
+    path: string;
+    data?: string;
+}
+interface FileWatchOptions {
+    recursive?: boolean;
+    onEvent: (event: FileWatchEvent) => void;
+}
 interface PortMapping {
     containerPort: number;
     hostPort: number;
@@ -116,6 +153,12 @@ declare class Filesystem {
     writeMany(files: FileWriteEntry[]): Promise<FileWriteManyResult>;
     rename(oldPath: string, newPath: string): Promise<void>;
     delete(filePath: string): Promise<void>;
+    stat(filePath: string): Promise<FileStat>;
+    readBytes(filePath: string): Promise<Uint8Array>;
+    writeBytes(filePath: string, data: Uint8Array | Buffer): Promise<void>;
+    watch(dirPath: string, opts: FileWatchOptions): Promise<{
+        close: () => void;
+    }>;
 }
 
 declare class Process extends EventEmitter {
@@ -144,6 +187,9 @@ declare class BackgroundProcess {
     }>;
     waitForPort(port: number, opts?: WaitForPortOptions): Promise<void>;
     waitForLog(pattern: string | RegExp, opts?: WaitForLogOptions): Promise<string>;
+    streamLogs(opts?: StreamLogsOptions): {
+        close: () => void;
+    };
 }
 declare class ProcessManager {
     private readonly sandboxId;
@@ -181,6 +227,7 @@ declare class Sandbox {
     readonly processes: ProcessManager;
     private constructor();
     private static resolveClient;
+    static list(opts?: SandboxListOptions): Promise<SandboxSummary[]>;
     static create(opts?: SandboxOptions): Promise<Sandbox>;
     /**
      * Reconnect to an existing sandbox by ID.
@@ -205,4 +252,4 @@ declare class Sandbox {
     close(): Promise<void>;
 }
 
-export { BackgroundProcess, type BackgroundProcessInfo, type ExecOptions, type ExecResult, type FileEntry, type FileWriteEntry, type FileWriteManyResult, Filesystem, type PortMapping, Process, ProcessManager, type ProxyEnvResult, Sandbox, type SandboxConnectOptions, type SandboxOptions, type StartProcessOptions, Terminal, type WaitForLogOptions, type WaitForPortOptions, type WsMessage, type WsMessageType };
+export { BackgroundProcess, type BackgroundProcessInfo, type ExecOptions, type ExecResult, type FileEntry, type FileStat, type FileWatchEvent, type FileWatchOptions, type FileWriteEntry, type FileWriteManyResult, Filesystem, type PortMapping, Process, ProcessManager, type ProxyEnvResult, Sandbox, type SandboxConnectOptions, type SandboxListOptions, type SandboxOptions, type SandboxSummary, type StartProcessOptions, type StreamLogsOptions, Terminal, type WaitForLogOptions, type WaitForPortOptions, type WsMessage, type WsMessageType };

package/dist/index.d.ts

@@ -30,11 +30,31 @@ interface SandboxOptions {
      */
     dockerfile?: string;
     timeout?: number;
+    /** Environment variables injected into the container for the entire session. */
+    env?: Record<string, string>;
 }
 interface SandboxConnectOptions {
     serverUrl?: string;
     apiKey?: string;
 }
+interface SandboxListOptions {
+    serverUrl?: string;
+    apiKey?: string;
+}
+interface SandboxSummary {
+    id: string;
+    status: string;
+    template: string;
+    createdAt: string;
+    timeout: number;
+    expiresAt: string | null;
+    agentUrl: string;
+    ports: Record<string, number>;
+}
+interface StreamLogsOptions {
+    onStdout?: (line: string) => void;
+    onStderr?: (line: string) => void;
+}
 interface StartProcessOptions {
     command?: string;
     cmd?: string;
@@ -92,6 +112,23 @@ interface FileWriteManyResult {
         error?: string;
     }>;
 }
+interface FileStat {
+    path: string;
+    size: number;
+    mtime: string;
+    isDirectory: boolean;
+    isFile: boolean;
+}
+interface FileWatchEvent {
+    type: 'change' | 'rename' | 'error';
+    eventType: 'create' | 'modify' | 'delete';
+    path: string;
+    data?: string;
+}
+interface FileWatchOptions {
+    recursive?: boolean;
+    onEvent: (event: FileWatchEvent) => void;
+}
 interface PortMapping {
     containerPort: number;
     hostPort: number;
@@ -116,6 +153,12 @@ declare class Filesystem {
     writeMany(files: FileWriteEntry[]): Promise<FileWriteManyResult>;
     rename(oldPath: string, newPath: string): Promise<void>;
     delete(filePath: string): Promise<void>;
+    stat(filePath: string): Promise<FileStat>;
+    readBytes(filePath: string): Promise<Uint8Array>;
+    writeBytes(filePath: string, data: Uint8Array | Buffer): Promise<void>;
+    watch(dirPath: string, opts: FileWatchOptions): Promise<{
+        close: () => void;
+    }>;
 }
 
 declare class Process extends EventEmitter {
@@ -144,6 +187,9 @@ declare class BackgroundProcess {
     }>;
     waitForPort(port: number, opts?: WaitForPortOptions): Promise<void>;
     waitForLog(pattern: string | RegExp, opts?: WaitForLogOptions): Promise<string>;
+    streamLogs(opts?: StreamLogsOptions): {
+        close: () => void;
+    };
 }
 declare class ProcessManager {
     private readonly sandboxId;
@@ -181,6 +227,7 @@ declare class Sandbox {
     readonly processes: ProcessManager;
     private constructor();
     private static resolveClient;
+    static list(opts?: SandboxListOptions): Promise<SandboxSummary[]>;
     static create(opts?: SandboxOptions): Promise<Sandbox>;
     /**
      * Reconnect to an existing sandbox by ID.
@@ -205,4 +252,4 @@ declare class Sandbox {
     close(): Promise<void>;
 }
 
-export { BackgroundProcess, type BackgroundProcessInfo, type ExecOptions, type ExecResult, type FileEntry, type FileWriteEntry, type FileWriteManyResult, Filesystem, type PortMapping, Process, ProcessManager, type ProxyEnvResult, Sandbox, type SandboxConnectOptions, type SandboxOptions, type StartProcessOptions, Terminal, type WaitForLogOptions, type WaitForPortOptions, type WsMessage, type WsMessageType };
+export { BackgroundProcess, type BackgroundProcessInfo, type ExecOptions, type ExecResult, type FileEntry, type FileStat, type FileWatchEvent, type FileWatchOptions, type FileWriteEntry, type FileWriteManyResult, Filesystem, type PortMapping, Process, ProcessManager, type ProxyEnvResult, Sandbox, type SandboxConnectOptions, type SandboxListOptions, type SandboxOptions, type SandboxSummary, type StartProcessOptions, type StreamLogsOptions, Terminal, type WaitForLogOptions, type WaitForPortOptions, type WsMessage, type WsMessageType };

package/dist/index.js

@@ -149,6 +149,49 @@ var Filesystem = class {
   async delete(filePath) {
     await this.client.delete(`/api/sandboxes/${this.sandboxId}/files`, { path: filePath });
   }
+  async stat(filePath) {
+    return this.client.get(
+      `/api/sandboxes/${this.sandboxId}/files/stat`,
+      { path: filePath }
+    );
+  }
+  async readBytes(filePath) {
+    const res = await this.client.get(
+      `/api/sandboxes/${this.sandboxId}/files/bytes`,
+      { path: filePath }
+    );
+    return Uint8Array.from(Buffer.from(res.data, "base64"));
+  }
+  async writeBytes(filePath, data) {
+    await this.client.post(`/api/sandboxes/${this.sandboxId}/files/bytes`, {
+      path: filePath,
+      data: Buffer.from(data).toString("base64")
+    });
+  }
+  async watch(dirPath, opts) {
+    const ws = this.client.openWebSocket(`/api/sandboxes/${this.sandboxId}/files/watch`);
+    await new Promise((resolve, reject) => {
+      ws.once("open", () => {
+        ws.send(JSON.stringify({ path: dirPath, recursive: opts.recursive ?? false }));
+        resolve();
+      });
+      ws.once("error", reject);
+    });
+    ws.on("message", (raw) => {
+      try {
+        const event = JSON.parse(raw.toString());
+        opts.onEvent(event);
+      } catch {
+      }
+    });
+    return {
+      close: () => {
+        if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING) {
+          ws.close();
+        }
+      }
+    };
+  }
 };
 
 // src/process.ts
@@ -239,6 +282,29 @@ var BackgroundProcess = class {
     );
     return res.match;
   }
+  streamLogs(opts = {}) {
+    const ws = this.client.openWebSocket(
+      `/api/sandboxes/${this.sandboxId}/processes/logs/stream`
+    );
+    ws.on("open", () => {
+      ws.send(JSON.stringify({ processId: this.id }));
+    });
+    ws.on("message", (raw) => {
+      try {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === "stdout") opts.onStdout?.(msg.data ?? "");
+        else if (msg.type === "stderr") opts.onStderr?.(msg.data ?? "");
+      } catch {
+      }
+    });
+    return {
+      close: () => {
+        if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING) {
+          ws.close();
+        }
+      }
+    };
+  }
 };
 var ProcessManager = class {
   constructor(sandboxId, client) {
@@ -329,12 +395,17 @@ var Sandbox = class _Sandbox {
     const apiKey = opts.apiKey ?? process.env.SANDBOX_API_KEY ?? "dev-api-key";
     return new HttpClient(serverUrl, apiKey);
   }
+  static async list(opts = {}) {
+    const client = _Sandbox.resolveClient(opts);
+    return client.get("/api/sandboxes");
+  }
   static async create(opts = {}) {
     const client = _Sandbox.resolveClient(opts);
     const data = await client.post("/api/sandboxes", {
       template: opts.template,
       dockerfile: opts.dockerfile,
-      timeout: opts.timeout
+      timeout: opts.timeout,
+      env: opts.env
     });
     return new _Sandbox(client, data.id);
   }

package/dist/index.mjs

@@ -108,6 +108,49 @@ var Filesystem = class {
   async delete(filePath) {
     await this.client.delete(`/api/sandboxes/${this.sandboxId}/files`, { path: filePath });
   }
+  async stat(filePath) {
+    return this.client.get(
+      `/api/sandboxes/${this.sandboxId}/files/stat`,
+      { path: filePath }
+    );
+  }
+  async readBytes(filePath) {
+    const res = await this.client.get(
+      `/api/sandboxes/${this.sandboxId}/files/bytes`,
+      { path: filePath }
+    );
+    return Uint8Array.from(Buffer.from(res.data, "base64"));
+  }
+  async writeBytes(filePath, data) {
+    await this.client.post(`/api/sandboxes/${this.sandboxId}/files/bytes`, {
+      path: filePath,
+      data: Buffer.from(data).toString("base64")
+    });
+  }
+  async watch(dirPath, opts) {
+    const ws = this.client.openWebSocket(`/api/sandboxes/${this.sandboxId}/files/watch`);
+    await new Promise((resolve, reject) => {
+      ws.once("open", () => {
+        ws.send(JSON.stringify({ path: dirPath, recursive: opts.recursive ?? false }));
+        resolve();
+      });
+      ws.once("error", reject);
+    });
+    ws.on("message", (raw) => {
+      try {
+        const event = JSON.parse(raw.toString());
+        opts.onEvent(event);
+      } catch {
+      }
+    });
+    return {
+      close: () => {
+        if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING) {
+          ws.close();
+        }
+      }
+    };
+  }
 };
 
 // src/process.ts
@@ -198,6 +241,29 @@ var BackgroundProcess = class {
     );
     return res.match;
   }
+  streamLogs(opts = {}) {
+    const ws = this.client.openWebSocket(
+      `/api/sandboxes/${this.sandboxId}/processes/logs/stream`
+    );
+    ws.on("open", () => {
+      ws.send(JSON.stringify({ processId: this.id }));
+    });
+    ws.on("message", (raw) => {
+      try {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === "stdout") opts.onStdout?.(msg.data ?? "");
+        else if (msg.type === "stderr") opts.onStderr?.(msg.data ?? "");
+      } catch {
+      }
+    });
+    return {
+      close: () => {
+        if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING) {
+          ws.close();
+        }
+      }
+    };
+  }
 };
 var ProcessManager = class {
   constructor(sandboxId, client) {
@@ -288,12 +354,17 @@ var Sandbox = class _Sandbox {
     const apiKey = opts.apiKey ?? process.env.SANDBOX_API_KEY ?? "dev-api-key";
     return new HttpClient(serverUrl, apiKey);
   }
+  static async list(opts = {}) {
+    const client = _Sandbox.resolveClient(opts);
+    return client.get("/api/sandboxes");
+  }
   static async create(opts = {}) {
     const client = _Sandbox.resolveClient(opts);
     const data = await client.post("/api/sandboxes", {
       template: opts.template,
       dockerfile: opts.dockerfile,
-      timeout: opts.timeout
+      timeout: opts.timeout,
+      env: opts.env
     });
     return new _Sandbox(client, data.id);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandbox-engine/sdk",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "SDK for creating and managing isolated sandbox environments",
   "keywords": ["sandbox", "docker", "code-execution", "isolated", "e2b"],
   "license": "MIT",