@sandbox-engine/sdk 0.1.4 → 0.2.1

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,10 +112,38 @@ 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 ExposePortOptions {
+    /** Human-readable label for this port (e.g. 'api', 'frontend'). */
+    name?: string;
+    /**
+     * Access token embedded in the preview URL.
+     * Use a stable value to get a consistent URL across sandbox restarts.
+     * When set, the URL becomes: https://{port}-{id}-{token}.{domain}
+     */
+    token?: string;
+}
 interface PortMapping {
     containerPort: number;
-    hostPort: number;
     url: string;
+    name?: string;
+    token?: string;
 }
 type WsMessageType = 'stdout' | 'stderr' | 'exit' | 'error' | 'input' | 'resize';
 interface WsMessage {
@@ -116,6 +164,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 +198,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 +238,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.
@@ -196,13 +254,31 @@ declare class Sandbox {
         getProxyEnv: (secretNames: string[]) => Promise<ProxyEnvResult>;
     };
     readonly ports: {
+        /**
+         * List all currently exposed ports for this sandbox.
+         */
         list: () => Promise<PortMapping[]>;
-        expose: (containerPort: number) => Promise<void>;
+        /**
+         * Expose any port (1024–65535) and get a public HTTPS URL.
+         *
+         * @example
+         * const { url } = await sandbox.ports.expose(5173, { name: 'vite', token: 'my-token' })
+         * // https://5173-{sandboxId}-my-token.preview.yourdomain.com
+         */
+        expose: (containerPort: number, opts?: ExposePortOptions) => Promise<PortMapping>;
+        /**
+         * Remove a port from public access.
+         */
         unexpose: (containerPort: number) => Promise<void>;
+        /**
+         * Check whether a token grants access to an exposed port.
+         * Returns true if the port has no token requirement or if the token matches.
+         */
+        validateToken: (containerPort: number, token: string) => Promise<boolean>;
     };
     info(): Promise<SandboxApiResponse>;
     keepalive(timeout?: number): Promise<SandboxApiResponse>;
     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,10 +112,38 @@ 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 ExposePortOptions {
+    /** Human-readable label for this port (e.g. 'api', 'frontend'). */
+    name?: string;
+    /**
+     * Access token embedded in the preview URL.
+     * Use a stable value to get a consistent URL across sandbox restarts.
+     * When set, the URL becomes: https://{port}-{id}-{token}.{domain}
+     */
+    token?: string;
+}
 interface PortMapping {
     containerPort: number;
-    hostPort: number;
     url: string;
+    name?: string;
+    token?: string;
 }
 type WsMessageType = 'stdout' | 'stderr' | 'exit' | 'error' | 'input' | 'resize';
 interface WsMessage {
@@ -116,6 +164,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 +198,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 +238,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.
@@ -196,13 +254,31 @@ declare class Sandbox {
         getProxyEnv: (secretNames: string[]) => Promise<ProxyEnvResult>;
     };
     readonly ports: {
+        /**
+         * List all currently exposed ports for this sandbox.
+         */
         list: () => Promise<PortMapping[]>;
-        expose: (containerPort: number) => Promise<void>;
+        /**
+         * Expose any port (1024–65535) and get a public HTTPS URL.
+         *
+         * @example
+         * const { url } = await sandbox.ports.expose(5173, { name: 'vite', token: 'my-token' })
+         * // https://5173-{sandboxId}-my-token.preview.yourdomain.com
+         */
+        expose: (containerPort: number, opts?: ExposePortOptions) => Promise<PortMapping>;
+        /**
+         * Remove a port from public access.
+         */
         unexpose: (containerPort: number) => Promise<void>;
+        /**
+         * Check whether a token grants access to an exposed port.
+         * Returns true if the port has no token requirement or if the token matches.
+         */
+        validateToken: (containerPort: number, token: string) => Promise<boolean>;
     };
     info(): Promise<SandboxApiResponse>;
     keepalive(timeout?: number): Promise<SandboxApiResponse>;
     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);
   }
@@ -398,22 +469,45 @@ var Sandbox = class _Sandbox {
     }
   };
   ports = {
+    /**
+     * List all currently exposed ports for this sandbox.
+     */
     list: async () => {
       const res = await this.client.get(
         `/api/sandboxes/${this.id}/ports`
       );
       return res.ports;
     },
-    expose: async (containerPort) => {
-      await this.client.post(
+    /**
+     * Expose any port (1024–65535) and get a public HTTPS URL.
+     *
+     * @example
+     * const { url } = await sandbox.ports.expose(5173, { name: 'vite', token: 'my-token' })
+     * // https://5173-{sandboxId}-my-token.preview.yourdomain.com
+     */
+    expose: async (containerPort, opts = {}) => {
+      return this.client.post(
         `/api/sandboxes/${this.id}/ports/${containerPort}/expose`,
-        {}
+        opts
       );
     },
+    /**
+     * Remove a port from public access.
+     */
     unexpose: async (containerPort) => {
       await this.client.delete(
         `/api/sandboxes/${this.id}/ports/${containerPort}/expose`
       );
+    },
+    /**
+     * Check whether a token grants access to an exposed port.
+     * Returns true if the port has no token requirement or if the token matches.
+     */
+    validateToken: async (containerPort, token) => {
+      const res = await this.client.get(
+        `/api/sandboxes/${this.id}/ports/${containerPort}/validate?token=${encodeURIComponent(token)}`
+      );
+      return res.valid;
     }
   };
   async info() {

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);
   }
@@ -357,22 +428,45 @@ var Sandbox = class _Sandbox {
     }
   };
   ports = {
+    /**
+     * List all currently exposed ports for this sandbox.
+     */
     list: async () => {
       const res = await this.client.get(
         `/api/sandboxes/${this.id}/ports`
       );
       return res.ports;
     },
-    expose: async (containerPort) => {
-      await this.client.post(
+    /**
+     * Expose any port (1024–65535) and get a public HTTPS URL.
+     *
+     * @example
+     * const { url } = await sandbox.ports.expose(5173, { name: 'vite', token: 'my-token' })
+     * // https://5173-{sandboxId}-my-token.preview.yourdomain.com
+     */
+    expose: async (containerPort, opts = {}) => {
+      return this.client.post(
         `/api/sandboxes/${this.id}/ports/${containerPort}/expose`,
-        {}
+        opts
       );
     },
+    /**
+     * Remove a port from public access.
+     */
     unexpose: async (containerPort) => {
       await this.client.delete(
         `/api/sandboxes/${this.id}/ports/${containerPort}/expose`
       );
+    },
+    /**
+     * Check whether a token grants access to an exposed port.
+     * Returns true if the port has no token requirement or if the token matches.
+     */
+    validateToken: async (containerPort, token) => {
+      const res = await this.client.get(
+        `/api/sandboxes/${this.id}/ports/${containerPort}/validate?token=${encodeURIComponent(token)}`
+      );
+      return res.valid;
     }
   };
   async info() {

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@sandbox-engine/sdk",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "SDK for creating and managing isolated sandbox environments",
-  "keywords": ["sandbox", "docker", "code-execution", "isolated", "e2b"],
+  "keywords": [
+    "sandbox",
+    "docker",
+    "code-execution",
+    "isolated",
+    "e2b"
+  ],
   "license": "MIT",
   "main": "dist/index.js",
   "module": "dist/index.mjs",