@sandbox-engine/sdk 0.2.0 → 0.2.1

package/dist/index.d.mts

@@ -129,10 +129,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 {
@@ -243,9 +254,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

@@ -129,10 +129,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 {
@@ -243,9 +254,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

@@ -469,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

@@ -428,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.2.0",
+  "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",