@sandbox-engine/sdk 0.2.0 → 0.2.2

package/dist/index.d.mts

@@ -1,6 +1,20 @@
-import WebSocket from 'ws';
 import { EventEmitter } from 'node:events';
 
+interface WsLike {
+    on(event: 'message', handler: (data: unknown) => void): void;
+    on(event: 'error', handler: (err: Error) => void): void;
+    on(event: 'close', handler: () => void): void;
+    on(event: 'open', handler: () => void): void;
+    once(event: 'message', handler: (data: unknown) => void): void;
+    once(event: 'error', handler: (err: Error) => void): void;
+    once(event: 'open', handler: () => void): void;
+    send(data: string): void;
+    close(): void;
+    readyState: number;
+    readonly OPEN: number;
+    readonly CONNECTING: number;
+}
+
 declare class HttpClient {
     private readonly baseUrl;
     private readonly apiKey;
@@ -9,7 +23,7 @@ declare class HttpClient {
     get<T>(path: string, query?: Record<string, string>): Promise<T>;
     post<T>(path: string, body?: unknown, timeoutMs?: number): Promise<T>;
     delete<T = void>(path: string, query?: Record<string, string>): Promise<T>;
-    openWebSocket(path: string): WebSocket;
+    openWebSocket(path: string): Promise<WsLike>;
 }
 
 interface SandboxOptions {
@@ -129,10 +143,21 @@ 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 {
@@ -163,7 +188,7 @@ declare class Filesystem {
 
 declare class Process extends EventEmitter {
     private ws;
-    constructor(ws: WebSocket);
+    constructor(ws: WsLike);
     kill(): void;
     wait(): Promise<ExecResult>;
 }
@@ -187,9 +212,9 @@ declare class BackgroundProcess {
     }>;
     waitForPort(port: number, opts?: WaitForPortOptions): Promise<void>;
     waitForLog(pattern: string | RegExp, opts?: WaitForLogOptions): Promise<string>;
-    streamLogs(opts?: StreamLogsOptions): {
+    streamLogs(opts?: StreamLogsOptions): Promise<{
         close: () => void;
-    };
+    }>;
 }
 declare class ProcessManager {
     private readonly sandboxId;
@@ -204,7 +229,7 @@ declare class ProcessManager {
 
 declare class Terminal extends EventEmitter {
     private ws;
-    constructor(ws: WebSocket);
+    constructor(ws: WsLike);
     write(data: string): void;
     resize(cols: number, rows: number): void;
     close(): void;
@@ -243,9 +268,27 @@ 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>;

package/dist/index.d.ts

@@ -1,6 +1,20 @@
-import WebSocket from 'ws';
 import { EventEmitter } from 'node:events';
 
+interface WsLike {
+    on(event: 'message', handler: (data: unknown) => void): void;
+    on(event: 'error', handler: (err: Error) => void): void;
+    on(event: 'close', handler: () => void): void;
+    on(event: 'open', handler: () => void): void;
+    once(event: 'message', handler: (data: unknown) => void): void;
+    once(event: 'error', handler: (err: Error) => void): void;
+    once(event: 'open', handler: () => void): void;
+    send(data: string): void;
+    close(): void;
+    readyState: number;
+    readonly OPEN: number;
+    readonly CONNECTING: number;
+}
+
 declare class HttpClient {
     private readonly baseUrl;
     private readonly apiKey;
@@ -9,7 +23,7 @@ declare class HttpClient {
     get<T>(path: string, query?: Record<string, string>): Promise<T>;
     post<T>(path: string, body?: unknown, timeoutMs?: number): Promise<T>;
     delete<T = void>(path: string, query?: Record<string, string>): Promise<T>;
-    openWebSocket(path: string): WebSocket;
+    openWebSocket(path: string): Promise<WsLike>;
 }
 
 interface SandboxOptions {
@@ -129,10 +143,21 @@ 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 {
@@ -163,7 +188,7 @@ declare class Filesystem {
 
 declare class Process extends EventEmitter {
     private ws;
-    constructor(ws: WebSocket);
+    constructor(ws: WsLike);
     kill(): void;
     wait(): Promise<ExecResult>;
 }
@@ -187,9 +212,9 @@ declare class BackgroundProcess {
     }>;
     waitForPort(port: number, opts?: WaitForPortOptions): Promise<void>;
     waitForLog(pattern: string | RegExp, opts?: WaitForLogOptions): Promise<string>;
-    streamLogs(opts?: StreamLogsOptions): {
+    streamLogs(opts?: StreamLogsOptions): Promise<{
         close: () => void;
-    };
+    }>;
 }
 declare class ProcessManager {
     private readonly sandboxId;
@@ -204,7 +229,7 @@ declare class ProcessManager {
 
 declare class Terminal extends EventEmitter {
     private ws;
-    constructor(ws: WebSocket);
+    constructor(ws: WsLike);
     write(data: string): void;
     resize(cols: number, rows: number): void;
     close(): void;
@@ -243,9 +268,27 @@ 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>;

package/dist/index.js

@@ -39,8 +39,37 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/ws-compat.ts
+var import_node_events = require("events");
+var WsEmitterAdapter = class extends import_node_events.EventEmitter {
+  constructor(ws) {
+    super();
+    this.ws = ws;
+    ws.accept?.();
+    ws.addEventListener("message", (e) => {
+      const raw = e.data;
+      this.emit("message", typeof raw === "string" ? raw : String(raw));
+    });
+    ws.addEventListener("error", (e) => this.emit("error", e));
+    ws.addEventListener("close", () => this.emit("close"));
+    ws.addEventListener("open", () => this.emit("open"));
+  }
+  ws;
+  OPEN = 1;
+  CONNECTING = 0;
+  get readyState() {
+    return this.ws.readyState;
+  }
+  send(data) {
+    this.ws.send(data);
+  }
+  close() {
+    this.ws.close();
+  }
+};
+var IS_CF_WORKERS = typeof globalThis.WebSocketPair !== "undefined";
+
 // src/client.ts
-var import_ws = __toESM(require("ws"));
 var HttpClient = class {
   constructor(baseUrl, apiKey) {
     this.baseUrl = baseUrl;
@@ -98,11 +127,26 @@ var HttpClient = class {
     if (!text) return void 0;
     return JSON.parse(text);
   }
-  openWebSocket(path) {
+  // ── WebSocket ───────────────────────────────────────────────────────────────
+  // CF Workers: uses fetch() with Upgrade header (supports Authorization).
+  // Node.js:    uses the ws package (installed as an optional dependency).
+  async openWebSocket(path) {
     const wsUrl = this.baseUrl.replace(/^http/, "ws") + path;
-    return new import_ws.default(wsUrl, {
-      headers: { authorization: `Bearer ${this.apiKey}` }
-    });
+    const authHeader = `Bearer ${this.apiKey}`;
+    if (IS_CF_WORKERS) {
+      const resp = await fetch(wsUrl, {
+        headers: {
+          Upgrade: "websocket",
+          Connection: "Upgrade",
+          Authorization: authHeader
+        }
+      });
+      const cfWs = resp.webSocket;
+      if (!cfWs) throw new Error("WebSocket upgrade failed \u2014 server did not accept");
+      return new WsEmitterAdapter(cfWs);
+    }
+    const { default: WS } = await import("ws");
+    return new WS(wsUrl, { headers: { authorization: authHeader } });
   }
 };
 
@@ -169,7 +213,7 @@ var Filesystem = class {
     });
   }
   async watch(dirPath, opts) {
-    const ws = this.client.openWebSocket(`/api/sandboxes/${this.sandboxId}/files/watch`);
+    const ws = await 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 }));
@@ -179,7 +223,7 @@ var Filesystem = class {
     });
     ws.on("message", (raw) => {
       try {
-        const event = JSON.parse(raw.toString());
+        const event = JSON.parse(String(raw));
         opts.onEvent(event);
       } catch {
       }
@@ -195,8 +239,8 @@ var Filesystem = class {
 };
 
 // src/process.ts
-var import_node_events = require("events");
-var Process = class extends import_node_events.EventEmitter {
+var import_node_events2 = require("events");
+var Process = class extends import_node_events2.EventEmitter {
   ws;
   constructor(ws) {
     super();
@@ -282,8 +326,8 @@ var BackgroundProcess = class {
     );
     return res.match;
   }
-  streamLogs(opts = {}) {
-    const ws = this.client.openWebSocket(
+  async streamLogs(opts = {}) {
+    const ws = await this.client.openWebSocket(
       `/api/sandboxes/${this.sandboxId}/processes/logs/stream`
     );
     ws.on("open", () => {
@@ -344,8 +388,8 @@ var ProcessManager = class {
 };
 
 // src/terminal.ts
-var import_node_events2 = require("events");
-var Terminal = class extends import_node_events2.EventEmitter {
+var import_node_events3 = require("events");
+var Terminal = class extends import_node_events3.EventEmitter {
   ws;
   constructor(ws) {
     super();
@@ -427,7 +471,7 @@ var Sandbox = class _Sandbox {
   async exec(cmd, opts = {}) {
     const { args, cwd, env, timeout, stream } = opts;
     if (stream) {
-      const ws = this.client.openWebSocket(`/api/sandboxes/${this.id}/exec/stream`);
+      const ws = await this.client.openWebSocket(`/api/sandboxes/${this.id}/exec/stream`);
       const proc = new Process(ws);
       await new Promise((resolve, reject) => {
         ws.once("open", () => {
@@ -454,7 +498,7 @@ var Sandbox = class _Sandbox {
     });
   }
   async terminal() {
-    const ws = this.client.openWebSocket(`/api/sandboxes/${this.id}/terminal`);
+    const ws = await this.client.openWebSocket(`/api/sandboxes/${this.id}/terminal`);
     await new Promise((resolve, reject) => {
       ws.once("open", resolve);
       ws.once("error", reject);
@@ -469,22 +513,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

@@ -1,5 +1,34 @@
+// src/ws-compat.ts
+import { EventEmitter } from "events";
+var WsEmitterAdapter = class extends EventEmitter {
+  constructor(ws) {
+    super();
+    this.ws = ws;
+    ws.accept?.();
+    ws.addEventListener("message", (e) => {
+      const raw = e.data;
+      this.emit("message", typeof raw === "string" ? raw : String(raw));
+    });
+    ws.addEventListener("error", (e) => this.emit("error", e));
+    ws.addEventListener("close", () => this.emit("close"));
+    ws.addEventListener("open", () => this.emit("open"));
+  }
+  ws;
+  OPEN = 1;
+  CONNECTING = 0;
+  get readyState() {
+    return this.ws.readyState;
+  }
+  send(data) {
+    this.ws.send(data);
+  }
+  close() {
+    this.ws.close();
+  }
+};
+var IS_CF_WORKERS = typeof globalThis.WebSocketPair !== "undefined";
+
 // src/client.ts
-import WebSocket from "ws";
 var HttpClient = class {
   constructor(baseUrl, apiKey) {
     this.baseUrl = baseUrl;
@@ -57,11 +86,26 @@ var HttpClient = class {
     if (!text) return void 0;
     return JSON.parse(text);
   }
-  openWebSocket(path) {
+  // ── WebSocket ───────────────────────────────────────────────────────────────
+  // CF Workers: uses fetch() with Upgrade header (supports Authorization).
+  // Node.js:    uses the ws package (installed as an optional dependency).
+  async openWebSocket(path) {
     const wsUrl = this.baseUrl.replace(/^http/, "ws") + path;
-    return new WebSocket(wsUrl, {
-      headers: { authorization: `Bearer ${this.apiKey}` }
-    });
+    const authHeader = `Bearer ${this.apiKey}`;
+    if (IS_CF_WORKERS) {
+      const resp = await fetch(wsUrl, {
+        headers: {
+          Upgrade: "websocket",
+          Connection: "Upgrade",
+          Authorization: authHeader
+        }
+      });
+      const cfWs = resp.webSocket;
+      if (!cfWs) throw new Error("WebSocket upgrade failed \u2014 server did not accept");
+      return new WsEmitterAdapter(cfWs);
+    }
+    const { default: WS } = await import("ws");
+    return new WS(wsUrl, { headers: { authorization: authHeader } });
   }
 };
 
@@ -128,7 +172,7 @@ var Filesystem = class {
     });
   }
   async watch(dirPath, opts) {
-    const ws = this.client.openWebSocket(`/api/sandboxes/${this.sandboxId}/files/watch`);
+    const ws = await 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 }));
@@ -138,7 +182,7 @@ var Filesystem = class {
     });
     ws.on("message", (raw) => {
       try {
-        const event = JSON.parse(raw.toString());
+        const event = JSON.parse(String(raw));
         opts.onEvent(event);
       } catch {
       }
@@ -154,8 +198,8 @@ var Filesystem = class {
 };
 
 // src/process.ts
-import { EventEmitter } from "events";
-var Process = class extends EventEmitter {
+import { EventEmitter as EventEmitter2 } from "events";
+var Process = class extends EventEmitter2 {
   ws;
   constructor(ws) {
     super();
@@ -241,8 +285,8 @@ var BackgroundProcess = class {
     );
     return res.match;
   }
-  streamLogs(opts = {}) {
-    const ws = this.client.openWebSocket(
+  async streamLogs(opts = {}) {
+    const ws = await this.client.openWebSocket(
       `/api/sandboxes/${this.sandboxId}/processes/logs/stream`
     );
     ws.on("open", () => {
@@ -303,8 +347,8 @@ var ProcessManager = class {
 };
 
 // src/terminal.ts
-import { EventEmitter as EventEmitter2 } from "events";
-var Terminal = class extends EventEmitter2 {
+import { EventEmitter as EventEmitter3 } from "events";
+var Terminal = class extends EventEmitter3 {
   ws;
   constructor(ws) {
     super();
@@ -386,7 +430,7 @@ var Sandbox = class _Sandbox {
   async exec(cmd, opts = {}) {
     const { args, cwd, env, timeout, stream } = opts;
     if (stream) {
-      const ws = this.client.openWebSocket(`/api/sandboxes/${this.id}/exec/stream`);
+      const ws = await this.client.openWebSocket(`/api/sandboxes/${this.id}/exec/stream`);
       const proc = new Process(ws);
       await new Promise((resolve, reject) => {
         ws.once("open", () => {
@@ -413,7 +457,7 @@ var Sandbox = class _Sandbox {
     });
   }
   async terminal() {
-    const ws = this.client.openWebSocket(`/api/sandboxes/${this.id}/terminal`);
+    const ws = await this.client.openWebSocket(`/api/sandboxes/${this.id}/terminal`);
     await new Promise((resolve, reject) => {
       ws.once("open", resolve);
       ws.once("error", reject);
@@ -428,22 +472,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.2.0",
+  "version": "0.2.2",
   "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",