@adobe/aio-lib-sandbox 0.1.0-alpha.6 → 0.1.0-alpha.8

package/.eslintignore

@@ -0,0 +1,2 @@
+node_modules/
+coverage/

package/.eslintrc.json

@@ -0,0 +1,21 @@
+{
+  "extends": ["@adobe/eslint-config-aio-lib-config"],
+  "settings": {
+    "jsdoc": {
+      "ignorePrivate": true
+    }
+  },
+  "rules": {
+    "no-param-reassign": ["warn", { "props": true }],
+    "jsdoc/tag-lines": [
+      "error",
+      "never",
+      {
+        "startLines": null
+      }
+    ]
+  },
+  "parserOptions": {
+    "ecmaVersion": 2020
+  }
+}

package/README.md

@@ -74,12 +74,19 @@ const { Sandbox } = require('@adobe/aio-lib-sandbox')
 const sandbox = await Sandbox.create({
   name:        'my-sandbox',
   type:        'cpu:default',
+  idleTimeout: 900,
   maxLifetime: 3600,
   ports:       [3000, 8080],
   envs:        { API_KEY: 'your-api-key' }
 })
 ```
 
+#### Sandbox lifetime model
+
+A sandbox is always deleted when `maxLifetime` has elapsed. It will also be deleted after the `idleTimeout` has elapsed, if there has been no activity.
+
+To keep a sandbox alive, send at least one command or check the status every `idleTimeout` seconds.
+
 ### Get Status
 
 ```js
@@ -218,3 +225,24 @@ const sandbox = await Sandbox.create({
   }
 })
 ```
+
+## Development
+
+Install development dependencies:
+
+```bash
+npm install
+```
+
+To run the same checks used by CI:
+
+```bash
+npm test
+```
+
+Linting is powered by ESLint:
+
+```bash
+npm run lint
+npm run lint-fix
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/aio-lib-sandbox",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "description": "JavaScript SDK for Adobe Runtime Sandboxes",
   "main": "src/index.js",
   "license": "Apache-2.0",
@@ -19,11 +19,22 @@
     "ws": "^8.19.0"
   },
   "devDependencies": {
+    "@adobe/eslint-config-aio-lib-config": "^4.0.0",
+    "eslint": "^8.57.1",
+    "eslint-config-standard": "^17.1.0",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-jest": "^27.9.0",
+    "eslint-plugin-jsdoc": "^48.11.0",
+    "eslint-plugin-n": "^15.7.0",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-promise": "^6.6.0",
     "jest": "^29",
     "jest-junit": "^16.0.0"
   },
   "scripts": {
-    "test": "jest --ci",
-    "lint": "node --check src/**/*.js"
+    "lint": "eslint src test",
+    "lint-fix": "eslint src test --fix",
+    "test": "npm run unit-tests && npm run lint",
+    "unit-tests": "jest --ci"
   }
 }

package/src/Sandbox.js

@@ -36,12 +36,13 @@ class Sandbox {
    * @param {object} options sandbox options
    * @private
    */
-  constructor(options) {
+  constructor (options) {
     this.id = options.id
     this.endpoint = options.endpoint
     this.status = options.status
     this.cluster = options.cluster
     this.region = options.region
+    this.idleTimeout = options.idleTimeout
     this.maxLifetime = options.maxLifetime
 
     this.namespace = options.namespace
@@ -70,13 +71,16 @@ class Sandbox {
    * @param {string} [options.name] sandbox display name
    * @param {string} [options.type] sandbox type (default: `'cpu:default'`)
    * @param {string|object} [options.size] sandbox size tier (name or spec object)
-   * @param {number} [options.maxLifetime] maximum lifetime in seconds
+   * @param {number} [options.idleTimeout] seconds of inactivity before the sandbox is terminated
+   *   (default: 900, max: 10800). The idle timer resets on every WebSocket message or status-check
+   *   request.
+   * @param {number} [options.maxLifetime] maximum lifetime in seconds (default: 3600, max: 10800)
    * @param {number[]} [options.ports] TCP ports to expose via preview URLs (default: `[]`)
    * @param {object} [options.envs] environment variables to inject into the sandbox
    * @param {object} [options.policy] network policy (e.g. egress allowlist)
    * @returns {Promise<Sandbox>} connected sandbox instance
    */
-  static async create(options = {}) {
+  static async create (options = {}) {
     console.warn('[aio-lib-sandbox] alpha — APIs may change without notice')
     const creds = resolveCredentials(options)
 
@@ -84,6 +88,7 @@ class Sandbox {
       name: options.name,
       size: normalizeSize(options.size),
       type: options.type || 'cpu:default',
+      idleTimeout: options.idleTimeout || 900,
       maxLifetime: options.maxLifetime || 3600
     }
 
@@ -93,7 +98,7 @@ class Sandbox {
     if (options.policy !== undefined) body.policy = options.policy
     if (options.ports !== undefined) body.ports = options.ports
 
-    const url = `${creds.apiHost}/api/v1/namespaces/${creds.namespace}/sandbox`
+    const url = `${creds.apiHost}/api/v1/namespaces/${creds.namespace}/sandboxes`
     const payload = await apiRequest('POST', url, creds.apiKey, body)
 
     const sandboxId = payload.sandboxId
@@ -105,6 +110,7 @@ class Sandbox {
       status: payload.status,
       cluster: payload.cluster,
       region: payload.region,
+      idleTimeout: payload.idleTimeout,
       maxLifetime: payload.maxLifetime,
       previewUrls: parsePreviewUrls(payload.previewUrls),
       managementEndpoint: payload.managementEndpoint || null,
@@ -124,17 +130,23 @@ class Sandbox {
    * Credentials are read from the environment automatically.
    * Any value passed explicitly in `options` overrides the environment.
    *
+   * Pass the management endpoint so the request is sent to the correct host;
+   * falls back to `options.apiHost` when omitted.
+   *
    * @param {string} sandboxId the sandbox ID to look up
    * @param {object} [options] credential overrides
    * @param {string} [options.apiHost] Runtime API host
    * @param {string} [options.namespace] Runtime namespace
    * @param {string} [options.auth] Runtime API key
+   * @param {string} [options.managementEndpoint] per-sandbox management endpoint returned by
+   *   `Sandbox.create()`. Falls back to `apiHost` otherwise.
    * @returns {Promise<Sandbox>} sandbox instance with `status` populated (not WebSocket-connected)
    */
-  static async get(sandboxId, options = {}) {
+  static async get (sandboxId, options = {}) {
     console.warn('[aio-lib-sandbox] alpha — APIs may change without notice')
     const creds = resolveCredentials(options)
-    const url = `${creds.apiHost}/api/v1/namespaces/${creds.namespace}/sandbox/${sandboxId}`
+    const base = options.managementEndpoint || creds.apiHost
+    const url = `${base}/api/v1/namespaces/${creds.namespace}/sandboxes/${sandboxId}`
     const payload = await apiRequest('GET', url, creds.apiKey)
 
     return new Sandbox({
@@ -143,7 +155,9 @@ class Sandbox {
       status: payload.status,
       cluster: payload.cluster,
       region: payload.region,
+      idleTimeout: payload.idleTimeout,
       maxLifetime: payload.maxLifetime,
+      managementEndpoint: payload.managementEndpoint || options.managementEndpoint || null,
       previewUrls: parsePreviewUrls(payload.previewUrls),
       namespace: creds.namespace,
       apiHost: creds.apiHost,
@@ -157,7 +171,7 @@ class Sandbox {
    *
    * @type {object}
    */
-  static get sizes() {
+  static get sizes () {
     return SANDBOX_SIZES
   }
 
@@ -165,19 +179,19 @@ class Sandbox {
    * Exposes `resolveCredentials` as a static helper (useful for testing).
    *
    * @param {object} overrides credential overrides
-   * @returns {{ apiHost: string, namespace: string, apiKey: string }}
+   * @returns {{ apiHost: string, namespace: string, apiKey: string }} resolved Runtime credentials
    */
-  static resolveCredentials(overrides = {}) {
+  static resolveCredentials (overrides = {}) {
     return resolveCredentials(overrides)
   }
 
   /**
    * Exposes `normalizeSize` as a static helper (useful for testing).
    *
-   * @param {string|object|undefined} size
-   * @returns {string}
+   * @param {string|object|undefined} size sandbox size name or resource spec
+   * @returns {string} normalized sandbox size name
    */
-  static normalizeSize(size) {
+  static normalizeSize (size) {
     return normalizeSize(size)
   }
 
@@ -190,7 +204,7 @@ class Sandbox {
    *
    * @returns {Promise<void>}
    */
-  connect() {
+  connect () {
     if (!this.ws) {
       this.ws = new SandboxSocket({
         id: this.id,
@@ -215,10 +229,10 @@ class Sandbox {
    * @param {number} [options.timeout] timeout in milliseconds (foreground only)
    * @param {boolean} [options.detached] when true, run as a detached background process
    * @param {string|Buffer} [options.stdin] data to send to stdin at startup
-   * @param {function} [options.onOutput] callback called with `(data, stream)` for each output chunk
-   * @returns {Promise}
+   * @param {Function} [options.onOutput] callback called with `(data, stream)` for each output chunk
+   * @returns {Promise} command result, or a detached command handle when `options.detached` is true
    */
-  exec(command, options = {}) {
+  exec (command, options = {}) {
     try {
       this.ensureOpen()
     } catch (error) {
@@ -238,12 +252,12 @@ class Sandbox {
   }
 
   /**
-   * @param {string} execId
+   * @param {string} execId execution id to run inside the sandbox
    * @param {string} command
    * @param {object} options
    * @private
    */
-  async sendExecFrameAndAwaitResponse(execId, command, options) {
+  async sendExecFrameAndAwaitResponse (execId, command, options) {
     const detached = !!options.detached
     const frame = { type: 'exec.run', execId, command, ...(detached && { detached: true }) }
 
@@ -283,10 +297,10 @@ class Sandbox {
    *
    * @param {string} execId the execId returned by the original `exec()` call
    * @param {object} [options] re-attach options
-   * @param {function} [options.onOutput] callback called with `(data, stream)` for live output
-   * @returns {Promise<{execId, command, pid, startedAt, detached, wait, kill, writeStdin, closeStdin}>}
+   * @param {Function} [options.onOutput] callback called with `(data, stream)` for live output
+   * @returns {Promise<{execId, command, pid, startedAt, detached, wait, kill, writeStdin, closeStdin}>} command handle
    */
-  getCommand(execId, options = {}) {
+  getCommand (execId, options = {}) {
     try {
       this.ensureOpen()
     } catch (error) {
@@ -320,7 +334,7 @@ class Sandbox {
    * @param {string} execId execution id
    * @param {string} [signal] signal to deliver (default: `'SIGTERM'`)
    */
-  kill(execId, signal = 'SIGTERM') {
+  kill (execId, signal = 'SIGTERM') {
     this.ensureOpen()
     this.sendFrame({ type: 'exec.kill', execId, signal })
   }
@@ -332,7 +346,7 @@ class Sandbox {
    * @param {string} execId execution id from `exec()`
    * @param {string|Buffer} data data to write
    */
-  writeStdin(execId, data) {
+  writeStdin (execId, data) {
     this.ensureOpen()
     const frame = { type: 'exec.input', execId }
     if (Buffer.isBuffer(data)) {
@@ -350,7 +364,7 @@ class Sandbox {
    *
    * @param {string} execId execution id from `exec()`
    */
-  closeStdin(execId) {
+  closeStdin (execId) {
     this.ensureOpen()
     this.sendFrame({ type: 'exec.endInput', execId })
   }
@@ -365,7 +379,7 @@ class Sandbox {
    * @param {string} path path inside the sandbox
    * @returns {Promise<string>} file contents as a UTF-8 string
    */
-  readFile(path) {
+  readFile (path) {
     try {
       this.ensureOpen()
     } catch (error) {
@@ -395,7 +409,7 @@ class Sandbox {
    * @param {string|Buffer} content file contents
    * @returns {Promise<{path: string, size: number, ok: boolean}>} write confirmation
    */
-  writeFile(path, content) {
+  writeFile (path, content) {
     try {
       this.ensureOpen()
     } catch (error) {
@@ -428,7 +442,7 @@ class Sandbox {
    * @param {string} path directory path inside the sandbox
    * @returns {Promise<Array<{name: string, type: string, size?: number}>>} directory entries
    */
-  listFiles(path) {
+  listFiles (path) {
     try {
       this.ensureOpen()
     } catch (error) {
@@ -479,7 +493,7 @@ class Sandbox {
     if (url === undefined) {
       throw new SandboxPortNotProvisionedError(
         `Port ${port} was not provisioned for sandbox '${this.id}'. ` +
-        "Declare it in create({ ports: [...] }) to get a preview URL."
+        'Declare it in create({ ports: [...] }) to get a preview URL.'
       )
     }
 
@@ -491,9 +505,9 @@ class Sandbox {
    *
    * @returns {Promise<object>} destroy response payload
    */
-  async destroy() {
+  async destroy () {
     const base = this.managementEndpoint || this.apiHost
-    const url = `${base}/api/v1/namespaces/${this.namespace}/sandbox/${this.id}`
+    const url = `${base}/api/v1/namespaces/${this.namespace}/sandboxes/${this.id}`
     this.ws?.beginIntentionalClose()
 
     let payload
@@ -516,33 +530,33 @@ class Sandbox {
   /**
    * Schedules a timeout that kills `execId` and rejects its pending entry.
    *
-   * @param {string} execId
+   * @param {string} execId exec identifier to reject when the timeout fires
    * @param {string} command human-readable command string (for the error message)
    * @param {number} ms timeout in milliseconds
    * @returns {ReturnType<setTimeout>} the timer handle (stored on the entry for cancellation)
    */
-  scheduleTimeout(execId, command, ms) {
+  scheduleTimeout (execId, command, ms) {
     return setTimeout(() => {
       try {
         this.kill(execId)
       } catch (_) {
         // ignore errors
       }
-      
+
       this.ws.rejectExec(execId, new SandboxTimeoutError(
         `Command '${command}' exceeded timeout of ${ms}ms`
       ))
     }, ms)
   }
 
-  ensureOpen() {
+  ensureOpen () {
     if (!this.ws) {
       throw new SandboxWebSocketError(`Sandbox '${this.id}' is not connected`)
     }
     this.ws.ensureOpen()
   }
 
-  sendFrame(frame) {
+  sendFrame (frame) {
     this.ws.send(frame)
   }
 }
@@ -556,7 +570,7 @@ class Sandbox {
  * every `getUrl()` call will throw `SandboxPortNotProvisionedError`).
  *
  * @param {object|null|undefined} raw the `previewUrls` field from the API response
- * @returns {Map<number, string>}
+ * @returns {Map<number, string>} preview URLs keyed by port number
  */
 function parsePreviewUrls (raw) {
   if (!raw || typeof raw !== 'object') {

package/src/utils.js

@@ -18,10 +18,23 @@ const {
 } = require('./errors')
 const { SANDBOX_SIZES } = require('./constants')
 
+/**
+ * Builds a Basic authorization header from a Runtime API key.
+ *
+ * @param {string} apiKey Runtime API key
+ * @returns {string} Basic authorization header value
+ */
 function buildAuthorizationHeader (apiKey) {
   return `Basic ${Buffer.from(apiKey).toString('base64')}`
 }
 
+/**
+ * Maps sandbox management API status codes to SDK error classes.
+ *
+ * @param {number} status HTTP response status
+ * @param {string} message error message
+ * @returns {SandboxClientError} SDK error matching the response status
+ */
 function createSandboxHttpError (status, message) {
   if (status === 401 || status === 403) {
     return new SandboxUnauthorizedError(message)
@@ -35,6 +48,12 @@ function createSandboxHttpError (status, message) {
   return new SandboxClientError(message)
 }
 
+/**
+ * Ensures the Runtime API host has a URL scheme.
+ *
+ * @param {string} host Runtime API host
+ * @returns {string} API host with a URL scheme
+ */
 function normalizeApiHost (host) {
   if (!host.match(/^https?:\/\//)) {
     return `https://${host}`
@@ -42,10 +61,18 @@ function normalizeApiHost (host) {
   return host
 }
 
+/**
+ * Builds the sandbox execution WebSocket endpoint from Runtime API details.
+ *
+ * @param {string} apiHost Runtime API host
+ * @param {string} namespace Runtime namespace
+ * @param {string} sandboxId sandbox id
+ * @returns {string} sandbox WebSocket endpoint
+ */
 function buildWebSocketEndpoint (apiHost, namespace, sandboxId) {
   const url = new URL(apiHost)
   url.protocol = url.protocol === 'http:' ? 'ws:' : 'wss:'
-  url.pathname = `/ws/v1/namespaces/${namespace}/sandbox/${sandboxId}/exec`
+  url.pathname = `/api/v1/namespaces/${namespace}/sandboxes/${sandboxId}/exec`
   url.search = ''
   return url.toString()
 }
@@ -55,7 +82,7 @@ function buildWebSocketEndpoint (apiHost, namespace, sandboxId) {
  * explicit overrides. Throws `SandboxInitializationError` for missing values.
  *
  * @param {object} overrides explicit credential overrides
- * @returns {{ apiHost: string, namespace: string, apiKey: string }}
+ * @returns {{ apiHost: string, namespace: string, apiKey: string }} resolved Runtime credentials
  */
 function resolveCredentials (overrides = {}) {
   const apiHost = overrides.apiHost || process.env.__OW_API_HOST

package/src/ws.js

@@ -25,7 +25,7 @@ const {
  */
 class SandboxSocket {
   /**
-   * @param {object} options
+   * @param {object} options socket options
    * @param {string} options.id sandbox id
    * @param {string} options.endpoint WebSocket endpoint URL
    * @param {string} options.token authentication token
@@ -144,7 +144,7 @@ class SandboxSocket {
   /**
    * Serialises `frame` and sends it over the socket.
    *
-   * @param {object} frame
+   * @param {object} frame WebSocket frame to send
    */
   send (frame) {
     this.socket.send(JSON.stringify(frame))
@@ -167,7 +167,7 @@ class SandboxSocket {
   /**
    * Closes the underlying socket.
    *
-   * @param {object} [options]
+   * @param {object} [options] close options
    * @param {boolean} [options.intentional] whether pending work should be drained without error
    */
   close ({ intentional = false } = {}) {
@@ -180,22 +180,22 @@ class SandboxSocket {
   // ------------------------------------------------------------------
 
   /**
-   * Registers a pending exec, sends the frame, and returns the promises 
+   * Registers a pending exec, sends the frame, and returns the promises
    * that will be settled by subsequent result or ack frames (for detached)
    *
-   * @param {string} execId
+   * @param {string} execId execution id for the pending command
    * @param {object} frame the frame to send (must include `type` and `execId`)
-   * @param {{ detached: boolean, onOutput?: Function }} options
-   * @returns {{ ackPromise: Promise, waitPromise: Promise|null }}
+   * @param {{ detached: boolean, onOutput?: Function }} options pending exec options
+   * @returns {{ ackPromise: Promise, waitPromise: Promise|null }} promises for ack and optional completion
    */
   sendExec (execId, frame, { detached, onOutput }) {
     let waitResolve, waitReject, waitPromise
     if (detached) {
-      waitPromise = new Promise((res, rej) => { waitResolve = res; waitReject = rej })
+      waitPromise = new Promise((resolve, reject) => { waitResolve = resolve; waitReject = reject })
     }
 
     let resolve, reject
-    const ackPromise = new Promise((res, rej) => { resolve = res; reject = rej })
+    const ackPromise = new Promise((_resolve, _reject) => { resolve = _resolve; reject = _reject })
 
     this.pendingExecs.set(execId, {
       resolve,
@@ -225,8 +225,8 @@ class SandboxSocket {
   /**
    * Stores a timer handle on a pending exec entry so it can be cleared on completion.
    *
-   * @param {string} execId
-   * @param {ReturnType<setTimeout>} handle
+   * @param {string} execId execution id for the pending command
+   * @param {ReturnType<setTimeout>} handle timeout handle to store
    */
   setExecTimeout (execId, handle) {
     const entry = this.pendingExecs.get(execId)
@@ -236,8 +236,8 @@ class SandboxSocket {
   /**
    * Rejects and removes a pending exec, clearing its timeout.
    *
-   * @param {string} execId
-   * @param {Error} error
+   * @param {string} execId execution id for the pending command
+   * @param {Error} error error used to reject the command
    */
   rejectExec (execId, error) {
     const pending = this.pendingExecs.get(execId)
@@ -256,8 +256,8 @@ class SandboxSocket {
   /**
    * Rejects and removes a pending file operation.
    *
-   * @param {string} execId
-   * @param {Error} error
+   * @param {string} execId file operation id
+   * @param {Error} error error used to reject the file operation
    */
   rejectFileOp (execId, error) {
     const pending = this.pendingFileOps.get(execId)
@@ -269,7 +269,7 @@ class SandboxSocket {
   /**
    * Resolves and removes a pending exec during an intentional sandbox shutdown.
    *
-   * @param {string} execId
+   * @param {string} execId execution id for the pending command
    */
   resolveExecOnIntentionalClose (execId) {
     const pending = this.pendingExecs.get(execId)
@@ -469,7 +469,7 @@ class SandboxSocket {
   /**
    * Handles exec.info (response to exec.get) and error frames routed from handleMessage.
    *
-   * @param {object} frame
+   * @param {object} frame exec.get response or error frame
    */
   handleGetFrame (frame) {
     const pending = this.pendingGetOps.get(frame.execId)
@@ -517,12 +517,12 @@ class SandboxSocket {
    *
    * @param {object} frame exec.info frame
    * @param {object} pending entry from pendingGetOps
-   * @returns {Promise}
+   * @returns {Promise} wait promise for the running command
    */
   resolveExecEntry (frame, pending) {
     const existingExec = this.pendingExecs.get(frame.execId)
     if (existingExec) {
-      this.mergeOnOutputCallback(existingExec, pending.onOutput)
+      existingExec.onOutput = this.mergeOnOutputCallback(existingExec.onOutput, pending.onOutput)
       return existingExec._waitPromise
     }
     return this.registerReattachedExec(frame, pending.onOutput)
@@ -531,13 +531,13 @@ class SandboxSocket {
   /**
    * Appends `onOutput` to an existing exec entry's callback chain, preserving the previous handler.
    *
-   * @param {object} existingExec entry from pendingExecs
+   * @param {Function|null|undefined} prev existing callback
    * @param {Function|undefined} onOutput new callback to add
+   * @returns {Function|null|undefined} merged callback
    */
-  mergeOnOutputCallback (existingExec, onOutput) {
-    if (!onOutput) return
-    const prev = existingExec.onOutput
-    existingExec.onOutput = (data, stream) => {
+  mergeOnOutputCallback (prev, onOutput) {
+    if (!onOutput) return prev
+    return (data, stream) => {
       if (prev) prev(data, stream)
       onOutput(data, stream)
     }
@@ -549,11 +549,11 @@ class SandboxSocket {
    *
    * @param {object} frame exec.info frame
    * @param {Function|undefined} onOutput output callback
-   * @returns {Promise}
+   * @returns {Promise} wait promise for the reattached command
    */
   registerReattachedExec (frame, onOutput) {
     let waitResolve, waitReject
-    const waitPromise = new Promise((res, rej) => { waitResolve = res; waitReject = rej })
+    const waitPromise = new Promise((resolve, reject) => { waitResolve = resolve; waitReject = reject })
     this.pendingExecs.set(frame.execId, {
       resolve: () => {},
       reject: () => {},
@@ -576,7 +576,7 @@ class SandboxSocket {
    * @param {object} frame exec.info frame
    * @param {Promise} waitPromise resolves when the process exits
    * @param {object} sandbox Sandbox instance for delegating control operations
-   * @returns {object}
+   * @returns {object} command handle with wait and control helpers
    */
   buildCommandObject (frame, waitPromise, sandbox) {
     const { execId } = frame

package/test/Sandbox.test.js

@@ -67,7 +67,7 @@ class FakeWebSocket extends EventEmitter {
 
 const BASE_OPTIONS = {
   id: 'sb-test',
-  endpoint: 'wss://runtime.example.net/ws/v1/namespaces/ns/sandbox/sb-test/exec',
+  endpoint: 'wss://runtime.example.net/api/v1/namespaces/ns/sandboxes/sb-test/exec',
   status: 'ready',
   namespace: 'ns',
   apiHost: 'https://runtime.example.net',
@@ -80,6 +80,9 @@ const BASE_OPTIONS = {
 
 let sockets
 
+/**
+ *
+ */
 function setupWebSocket () {
   sockets = []
   WebSocket.OPEN = 1
@@ -90,6 +93,12 @@ function setupWebSocket () {
   })
 }
 
+/**
+ * Builds a connected sandbox backed by the fake WebSocket.
+ *
+ * @param {object} opts sandbox option overrides
+ * @returns {Promise<Sandbox>} connected sandbox instance
+ */
 async function buildConnectedSandbox (opts = {}) {
   const sandbox = new Sandbox({ ...BASE_OPTIONS, ...opts })
   const connectPromise = sandbox.connect()
@@ -200,7 +209,7 @@ describe('Sandbox', () => {
         ok: true,
         json: () => Promise.resolve({
           sandboxId: 'sb-new',
-          wsEndpoint: 'wss://runtime.example.net/ws/v1/namespaces/ns/sandbox/sb-new/exec',
+          wsEndpoint: 'wss://runtime.example.net/api/v1/namespaces/ns/sandboxes/sb-new/exec',
           status: 'ready',
           token: 'tok-new',
           maxLifetime: 3600,
@@ -231,7 +240,7 @@ describe('Sandbox', () => {
         [3000, 'https://sb-new-3000.preview.example.net']
       ]))
       expect(mockFetch).toHaveBeenCalledWith(
-        'https://runtime.example.net/api/v1/namespaces/ns/sandbox',
+        'https://runtime.example.net/api/v1/namespaces/ns/sandboxes',
         expect.objectContaining({ method: 'POST' })
       )
     })
@@ -241,7 +250,7 @@ describe('Sandbox', () => {
         ok: true,
         json: () => Promise.resolve({
           sandboxId: 'sb-pol',
-          wsEndpoint: 'wss://runtime.example.net/ws/v1/namespaces/ns/sandbox/sb-pol/exec',
+          wsEndpoint: 'wss://runtime.example.net/api/v1/namespaces/ns/sandboxes/sb-pol/exec',
           status: 'ready',
           token: 'tok-pol',
           maxLifetime: 3600
@@ -272,7 +281,7 @@ describe('Sandbox', () => {
         ok: true,
         json: () => Promise.resolve({
           sandboxId: 'sb-ports',
-          wsEndpoint: 'wss://runtime.example.net/ws/v1/namespaces/ns/sandbox/sb-ports/exec',
+          wsEndpoint: 'wss://runtime.example.net/api/v1/namespaces/ns/sandboxes/sb-ports/exec',
           status: 'ready',
           token: 'tok-ports',
           maxLifetime: 3600,
@@ -312,7 +321,7 @@ describe('Sandbox', () => {
         ok: true,
         json: () => Promise.resolve({
           sandboxId: 'sb-env',
-          wsEndpoint: 'wss://runtime.example.net/ws/v1/namespaces/ns/sandbox/sb-env/exec',
+          wsEndpoint: 'wss://runtime.example.net/api/v1/namespaces/ns/sandboxes/sb-env/exec',
           status: 'ready',
           token: 'tok-env',
           maxLifetime: 3600
@@ -333,6 +342,98 @@ describe('Sandbox', () => {
       await expect(Sandbox.create({ name: 'no-creds' })).rejects.toThrow(SandboxInitializationError)
     })
 
+    test('sends default idleTimeout 900 and maxLifetime 3600 when not specified', async () => {
+      const mockFetch = jest.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          sandboxId: 'sb-defaults',
+          wsEndpoint: 'wss://runtime.example.net/api/v1/namespaces/ns/sandboxes/sb-defaults/exec',
+          status: 'ready',
+          token: 'tok-defaults',
+          idleTimeout: 900,
+          maxLifetime: 3600
+        })
+      })
+      global.fetch = mockFetch
+
+      const createPromise = Sandbox.create({
+        name: 'defaults-sandbox',
+        apiHost: 'https://runtime.example.net',
+        namespace: 'ns',
+        auth: 'uuid:key'
+      })
+
+      await new Promise(resolve => setImmediate(resolve))
+      sockets[0].open()
+      sockets[0].message({ type: 'auth.ok', sandboxId: 'sb-defaults' })
+      await createPromise
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body)
+      expect(body.idleTimeout).toBe(900)
+      expect(body.maxLifetime).toBe(3600)
+    })
+
+    test('forwards explicit idleTimeout in the request body', async () => {
+      const mockFetch = jest.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          sandboxId: 'sb-idle',
+          wsEndpoint: 'wss://runtime.example.net/api/v1/namespaces/ns/sandboxes/sb-idle/exec',
+          status: 'ready',
+          token: 'tok-idle',
+          idleTimeout: 1800,
+          maxLifetime: 3600
+        })
+      })
+      global.fetch = mockFetch
+
+      const createPromise = Sandbox.create({
+        name: 'idle-sandbox',
+        apiHost: 'https://runtime.example.net',
+        namespace: 'ns',
+        auth: 'uuid:key',
+        idleTimeout: 1800
+      })
+
+      await new Promise(resolve => setImmediate(resolve))
+      sockets[0].open()
+      sockets[0].message({ type: 'auth.ok', sandboxId: 'sb-idle' })
+      await createPromise
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body)
+      expect(body.idleTimeout).toBe(1800)
+    })
+
+    test('stores idleTimeout from the create response on the instance', async () => {
+      const mockFetch = jest.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          sandboxId: 'sb-store',
+          wsEndpoint: 'wss://runtime.example.net/api/v1/namespaces/ns/sandboxes/sb-store/exec',
+          status: 'ready',
+          token: 'tok-store',
+          idleTimeout: 1800,
+          maxLifetime: 3600
+        })
+      })
+      global.fetch = mockFetch
+
+      const createPromise = Sandbox.create({
+        name: 'store-sandbox',
+        apiHost: 'https://runtime.example.net',
+        namespace: 'ns',
+        auth: 'uuid:key',
+        idleTimeout: 1800
+      })
+
+      await new Promise(resolve => setImmediate(resolve))
+      sockets[0].open()
+      sockets[0].message({ type: 'auth.ok', sandboxId: 'sb-store' })
+      const sandbox = await createPromise
+
+      expect(sandbox.idleTimeout).toBe(1800)
+    })
+
     test('falls back to buildWebSocketEndpoint when wsEndpoint absent', async () => {
       const mockFetch = jest.fn().mockResolvedValue({
         ok: true,
@@ -355,7 +456,7 @@ describe('Sandbox', () => {
       await new Promise(resolve => setImmediate(resolve))
       sockets[0].open()
       sockets[0].message({ type: 'auth.ok', sandboxId: 'sb-noep' })
-      const sandbox = await createPromise
+      await createPromise
 
       expect(sockets[0].url).toContain('wss://')
       expect(sockets[0].url).toContain('sb-noep')
@@ -385,6 +486,26 @@ describe('Sandbox', () => {
       expect(sandbox.cluster).toBe('cluster-b')
     })
 
+    test('stores idleTimeout from the get response on the instance', async () => {
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          sandboxId: 'sb-get-idle',
+          status: 'running',
+          idleTimeout: 1200,
+          maxLifetime: 3600
+        })
+      })
+
+      const sandbox = await Sandbox.get('sb-get-idle', {
+        apiHost: 'https://runtime.example.net',
+        namespace: 'ns',
+        auth: 'uuid:key'
+      })
+
+      expect(sandbox.idleTimeout).toBe(1200)
+    })
+
     test('throws SandboxNotFoundError on 404', async () => {
       global.fetch = jest.fn().mockResolvedValue({
         ok: false,
@@ -408,6 +529,38 @@ describe('Sandbox', () => {
         Sandbox.get('sb-x', { apiHost: 'https://runtime.example.net', namespace: 'ns', auth: 'bad' })
       ).rejects.toThrow(SandboxUnauthorizedError)
     })
+
+    test('throws SandboxTimeoutError on 504', async () => {
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: false,
+        status: 504,
+        text: () => Promise.resolve('gateway timeout')
+      })
+
+      await expect(
+        Sandbox.get('sb-slow', { apiHost: 'https://runtime.example.net', namespace: 'ns', auth: 'key' })
+      ).rejects.toThrow(SandboxTimeoutError)
+    })
+
+    test('throws SandboxClientError on unexpected API status', async () => {
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: false,
+        status: 500,
+        text: () => Promise.resolve('server error')
+      })
+
+      await expect(
+        Sandbox.get('sb-error', { apiHost: 'https://runtime.example.net', namespace: 'ns', auth: 'key' })
+      ).rejects.toThrow(SandboxClientError)
+    })
+
+    test('wraps fetch failures in SandboxClientError', async () => {
+      global.fetch = jest.fn().mockRejectedValue(new Error('network unavailable'))
+
+      await expect(
+        Sandbox.get('sb-network', { apiHost: 'https://runtime.example.net', namespace: 'ns', auth: 'key' })
+      ).rejects.toThrow(SandboxClientError)
+    })
   })
 
   // -------------------------------------------------------------------------
@@ -844,7 +997,7 @@ describe('Sandbox', () => {
       expect(result.status).toBe('destroyed')
       expect(sandbox.status).toBe('destroyed')
       expect(mockFetch).toHaveBeenCalledWith(
-        expect.stringContaining('/sandbox/sb-test'),
+        expect.stringContaining('/sandboxes/sb-test'),
         expect.objectContaining({ method: 'DELETE' })
       )
     })