@magpiecloud/mags 1.8.8 → 1.8.10

package/index.js

@@ -1,24 +1,46 @@
 /**
  * Mags SDK - Execute scripts on Magpie's instant VM infrastructure
+ * @module @magpiecloud/mags
  */
 
 const https = require('https');
 const http = require('http');
 const { URL } = require('url');
 
+class MagsError extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.name = 'MagsError';
+    this.statusCode = statusCode || null;
+  }
+}
+
 class Mags {
+  /**
+   * Create a Mags client
+   * @param {object} options - Configuration options
+   * @param {string} options.apiUrl - API endpoint (default: https://api.magpiecloud.com)
+   * @param {string} options.apiToken - API token (required, or set MAGS_API_TOKEN env var)
+   * @param {number} options.timeout - Default request timeout in ms (default: 30000)
+   */
   constructor(options = {}) {
-    this.apiUrl = options.apiUrl || process.env.MAGS_API_URL || 'https://api.magpiecloud.com';
-    this.apiToken = options.apiToken || process.env.MAGS_API_TOKEN;
+    this.apiUrl = (options.apiUrl || process.env.MAGS_API_URL || 'https://api.magpiecloud.com').replace(/\/+$/, '');
+    this.apiToken = options.apiToken || process.env.MAGS_API_TOKEN || process.env.MAGS_TOKEN;
+    this.timeout = options.timeout || 30000;
 
     if (!this.apiToken) {
-      throw new Error('API token required. Set MAGS_API_TOKEN or pass apiToken option.');
+      throw new MagsError('API token required. Set MAGS_API_TOKEN or pass apiToken option.');
     }
   }
 
-  _request(method, path, body = null) {
+  _request(method, path, body = null, params = null) {
     return new Promise((resolve, reject) => {
       const url = new URL(path, this.apiUrl);
+      if (params) {
+        for (const [k, v] of Object.entries(params)) {
+          url.searchParams.set(k, v);
+        }
+      }
       const isHttps = url.protocol === 'https:';
       const lib = isHttps ? https : http;
 
@@ -30,7 +52,8 @@ class Mags {
         headers: {
           'Authorization': `Bearer ${this.apiToken}`,
           'Content-Type': 'application/json'
-        }
+        },
+        timeout: this.timeout
       };
 
       const req = lib.request(options, (res) => {
@@ -40,49 +63,110 @@ class Mags {
           try {
             const parsed = JSON.parse(data);
             if (res.statusCode >= 400) {
-              reject(new Error(parsed.error || parsed.message || `HTTP ${res.statusCode}`));
+              reject(new MagsError(parsed.error || parsed.message || `HTTP ${res.statusCode}`, res.statusCode));
             } else {
               resolve(parsed);
             }
           } catch {
-            resolve(data);
+            if (res.statusCode >= 400) {
+              reject(new MagsError(data || `HTTP ${res.statusCode}`, res.statusCode));
+            } else {
+              resolve(data);
+            }
           }
         });
       });
 
       req.on('error', reject);
+      req.on('timeout', () => {
+        req.destroy();
+        reject(new MagsError('Request timed out'));
+      });
       if (body) req.write(JSON.stringify(body));
       req.end();
     });
   }
 
+  // ── Jobs ──────────────────────────────────────────────────────────
+
   /**
    * Submit a job for execution
    * @param {string} script - Script to execute
    * @param {object} options - Job options
    * @param {string} options.name - Job name
    * @param {string} options.workspaceId - Persistent workspace ID
+   * @param {string} options.baseWorkspaceId - Read-only base workspace to mount
    * @param {boolean} options.persistent - Keep VM alive after script
+   * @param {boolean} options.noSleep - Never auto-sleep (requires persistent)
+   * @param {boolean} options.ephemeral - No workspace/S3 sync (fastest)
    * @param {string} options.startupCommand - Command to run when waking from sleep
    * @param {object} options.environment - Environment variables
-   * @returns {Promise<{requestId: string, status: string}>}
+   * @param {string[]} options.fileIds - File IDs from uploadFiles()
+   * @param {number} options.diskGb - Custom disk size in GB (default 2)
+   * @returns {Promise<{request_id: string, status: string}>}
    */
   async run(script, options = {}) {
+    if (options.ephemeral && options.workspaceId) {
+      throw new MagsError('Cannot use ephemeral with workspaceId');
+    }
+    if (options.ephemeral && options.persistent) {
+      throw new MagsError('Cannot use ephemeral with persistent');
+    }
+    if (options.noSleep && !options.persistent) {
+      throw new MagsError('noSleep requires persistent=true');
+    }
+
     const payload = {
       script,
       type: 'inline',
-      name: options.name,
-      workspace_id: options.workspaceId,
       persistent: options.persistent || false,
-      startup_command: options.startupCommand,
-      environment: options.environment
     };
 
-    const response = await this._request('POST', '/api/v1/mags-jobs', payload);
-    return {
-      requestId: response.request_id,
-      status: response.status
-    };
+    if (options.noSleep) payload.no_sleep = true;
+    if (options.name) payload.name = options.name;
+    if (!options.ephemeral && options.workspaceId) payload.workspace_id = options.workspaceId;
+    if (options.baseWorkspaceId) payload.base_workspace_id = options.baseWorkspaceId;
+    if (options.startupCommand) payload.startup_command = options.startupCommand;
+    if (options.environment) payload.environment = options.environment;
+    if (options.fileIds && options.fileIds.length > 0) payload.file_ids = options.fileIds;
+    if (options.diskGb) payload.disk_gb = options.diskGb;
+
+    return this._request('POST', '/api/v1/mags-jobs', payload);
+  }
+
+  /**
+   * Run a job and wait for completion
+   * @param {string} script - Script to execute
+   * @param {object} options - Job options (same as run() plus timeout/pollInterval)
+   * @param {number} options.timeout - Timeout in ms (default: 60000)
+   * @param {number} options.pollInterval - Poll interval in ms (default: 1000)
+   * @returns {Promise<{requestId: string, status: string, exitCode: number, durationMs: number, logs: Array}>}
+   */
+  async runAndWait(script, options = {}) {
+    const timeout = options.timeout || 60000;
+    const pollInterval = options.pollInterval || 1000;
+    const result = await this.run(script, options);
+    const requestId = result.request_id;
+
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+      const status = await this.status(requestId);
+
+      if (status.status === 'completed' || status.status === 'error') {
+        const logsResp = await this.logs(requestId);
+        return {
+          requestId,
+          status: status.status,
+          exitCode: status.exit_code,
+          durationMs: status.script_duration_ms,
+          logs: logsResp.logs || []
+        };
+      }
+
+      await new Promise(resolve => setTimeout(resolve, pollInterval));
+    }
+
+    throw new MagsError(`Job ${requestId} timed out after ${timeout}ms`);
   }
 
   /**
@@ -113,52 +197,446 @@ class Mags {
   async list(options = {}) {
     const page = options.page || 1;
     const pageSize = options.pageSize || 20;
-    return this._request('GET', `/api/v1/mags-jobs?page=${page}&page_size=${pageSize}`);
+    return this._request('GET', `/api/v1/mags-jobs`, null, { page, page_size: pageSize });
   }
 
   /**
-   * Enable URL access for a job
+   * Update a job's settings
    * @param {string} requestId - Job request ID
-   * @param {number} port - Port to expose (default: 8080)
+   * @param {object} options - Settings to update
+   * @param {string} options.startupCommand - Command to run when VM wakes from sleep
+   * @param {boolean} options.noSleep - If true, VM never auto-sleeps. If false, re-enables auto-sleep.
+   * @returns {Promise<object>}
+   */
+  async updateJob(requestId, options = {}) {
+    const payload = {};
+    if (options.startupCommand !== undefined) payload.startup_command = options.startupCommand;
+    if (options.noSleep !== undefined) payload.no_sleep = options.noSleep;
+    return this._request('PATCH', `/api/v1/mags-jobs/${requestId}`, payload);
+  }
+
+  /**
+   * Enable URL or SSH access for a job
+   * @param {string} requestId - Job request ID
+   * @param {number} port - Port to expose (default: 8080, use 22 for SSH)
    * @returns {Promise<object>}
    */
-  async enableUrl(requestId, port = 8080) {
+  async enableAccess(requestId, port = 8080) {
     return this._request('POST', `/api/v1/mags-jobs/${requestId}/access`, { port });
   }
 
   /**
-   * Run a job and wait for completion
-   * @param {string} script - Script to execute
-   * @param {object} options - Job options
-   * @param {number} options.timeout - Timeout in ms (default: 60000)
-   * @returns {Promise<{status: string, exitCode: number, logs: Array}>}
+   * Enable public URL access for a job's VM
+   * @param {string} nameOrId - Job name, workspace ID, or request ID
+   * @param {number} port - Port to expose (default: 8080)
+   * @returns {Promise<object>} Object with url and access details
    */
-  async runAndWait(script, options = {}) {
-    const timeout = options.timeout || 60000;
-    const { requestId } = await this.run(script, options);
+  async url(nameOrId, port = 8080) {
+    const requestId = await this._resolveJobId(nameOrId);
+    const st = await this.status(requestId);
+    const resp = await this.enableAccess(requestId, port);
+    const subdomain = st.subdomain || resp.subdomain;
+    if (subdomain) {
+      resp.url = `https://${subdomain}.apps.magpiecloud.com`;
+    }
+    return resp;
+  }
+
+  /**
+   * Stop a running job. Accepts a job ID, job name, or workspace ID.
+   * @param {string} nameOrId - Job name, workspace ID, or request ID
+   * @returns {Promise<object>}
+   */
+  async stop(nameOrId) {
+    const requestId = await this._resolveJobId(nameOrId);
+    return this._request('POST', `/api/v1/mags-jobs/${requestId}/stop`);
+  }
+
+  /**
+   * Sync a running job's workspace to S3 without stopping the VM
+   * @param {string} requestId - Job request ID
+   * @returns {Promise<object>}
+   */
+  async sync(requestId) {
+    return this._request('POST', `/api/v1/mags-jobs/${requestId}/sync`);
+  }
+
+  /**
+   * Create a new persistent VM workspace and wait until it's running
+   * @param {string} name - Workspace name
+   * @param {object} options - Options
+   * @param {string} options.baseWorkspaceId - Read-only base workspace to mount
+   * @param {number} options.diskGb - Custom disk size in GB
+   * @param {number} options.timeout - Timeout in ms (default: 30000)
+   * @param {number} options.pollInterval - Poll interval in ms (default: 1000)
+   * @returns {Promise<{request_id: string, status: string}>}
+   */
+  async new(name, options = {}) {
+    const timeout = options.timeout || 30000;
+    const pollInterval = options.pollInterval || 1000;
+
+    const result = await this.run('sleep infinity', {
+      workspaceId: name,
+      persistent: true,
+      baseWorkspaceId: options.baseWorkspaceId,
+      diskGb: options.diskGb,
+    });
+    const requestId = result.request_id;
 
     const startTime = Date.now();
     while (Date.now() - startTime < timeout) {
-      const status = await this.status(requestId);
+      const st = await this.status(requestId);
+      if (st.status === 'running' && st.vm_id) {
+        return { request_id: requestId, status: 'running' };
+      }
+      if (st.status === 'completed' || st.status === 'error') {
+        throw new MagsError(`Job ${requestId} ended unexpectedly: ${st.status}`);
+      }
+      await new Promise(resolve => setTimeout(resolve, pollInterval));
+    }
 
-      if (status.status === 'completed' || status.status === 'error') {
-        const logsResp = await this.logs(requestId);
-        return {
-          requestId,
-          status: status.status,
-          exitCode: status.exit_code,
-          durationMs: status.script_duration_ms,
-          logs: logsResp.logs || []
-        };
+    throw new MagsError(`Job ${requestId} did not start within ${timeout}ms`);
+  }
+
+  /**
+   * Find a running or sleeping job by name, workspace ID, or job ID
+   * @param {string} nameOrId - Job name, workspace ID, or request ID
+   * @returns {Promise<object|null>} The job object, or null if not found
+   */
+  async findJob(nameOrId) {
+    const resp = await this.list({ pageSize: 50 });
+    const jobs = resp.jobs || [];
+
+    // Priority 1: exact name match, running/sleeping
+    for (const j of jobs) {
+      if (j.name === nameOrId && (j.status === 'running' || j.status === 'sleeping')) return j;
+    }
+    // Priority 2: workspace_id match, running/sleeping
+    for (const j of jobs) {
+      if (j.workspace_id === nameOrId && (j.status === 'running' || j.status === 'sleeping')) return j;
+    }
+    // Priority 3: exact name match, any status
+    for (const j of jobs) {
+      if (j.name === nameOrId) return j;
+    }
+    // Priority 4: workspace_id match, any status
+    for (const j of jobs) {
+      if (j.workspace_id === nameOrId) return j;
+    }
+
+    return null;
+  }
+
+  /**
+   * Execute a command on an existing running/sleeping VM via SSH
+   * @param {string} nameOrId - Job name, workspace ID, or request ID
+   * @param {string} command - Command to execute
+   * @param {object} options - Options
+   * @param {number} options.timeout - Timeout in ms (default: 30000)
+   * @returns {Promise<{exitCode: number, output: string, stderr: string}>}
+   */
+  async exec(nameOrId, command, options = {}) {
+    const timeout = options.timeout || 30000;
+
+    const job = await this.findJob(nameOrId);
+    if (!job) throw new MagsError(`No running or sleeping VM found for '${nameOrId}'`);
+    if (job.status !== 'running' && job.status !== 'sleeping') {
+      throw new MagsError(`VM for '${nameOrId}' is ${job.status}, needs to be running or sleeping`);
+    }
+
+    const requestId = job.request_id || job.id;
+    const access = await this.enableAccess(requestId, 22);
+
+    if (!access.success || !access.ssh_host) {
+      throw new MagsError(`Failed to enable SSH access: ${access.error || 'unknown error'}`);
+    }
+
+    const { execFile } = require('child_process');
+    const fs = require('fs');
+    const os = require('os');
+    const path = require('path');
+
+    const escaped = command.replace(/'/g, "'\\''");
+    const wrapped =
+      `if [ -d /overlay/bin ]; then ` +
+      `chroot /overlay /bin/sh -l -c 'cd /root 2>/dev/null; ${escaped}'; ` +
+      `else cd /root 2>/dev/null; ${escaped}; fi`;
+
+    let keyFile = null;
+    try {
+      const sshArgs = [
+        '-o', 'StrictHostKeyChecking=no',
+        '-o', 'UserKnownHostsFile=/dev/null',
+        '-o', 'LogLevel=ERROR',
+        '-p', String(access.ssh_port),
+      ];
+
+      if (access.ssh_private_key) {
+        keyFile = path.join(os.tmpdir(), `mags_ssh_${Date.now()}`);
+        fs.writeFileSync(keyFile, access.ssh_private_key, { mode: 0o600 });
+        sshArgs.push('-i', keyFile);
       }
 
+      sshArgs.push(`root@${access.ssh_host}`, wrapped);
+
+      return new Promise((resolve, reject) => {
+        execFile('ssh', sshArgs, { timeout, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+          if (keyFile) try { fs.unlinkSync(keyFile); } catch {}
+          if (err && err.killed) {
+            reject(new MagsError(`Command timed out after ${timeout}ms`));
+          } else {
+            resolve({
+              exitCode: err ? err.code || 1 : 0,
+              output: stdout,
+              stderr: stderr,
+            });
+          }
+        });
+      });
+    } catch (e) {
+      if (keyFile) try { require('fs').unlinkSync(keyFile); } catch {}
+      throw e;
+    }
+  }
+
+  /**
+   * Resize a workspace's disk. Stops the existing VM, then creates a new one.
+   * @param {string} workspace - Workspace name
+   * @param {number} diskGb - New disk size in GB
+   * @param {object} options - Options
+   * @param {number} options.timeout - Timeout in ms (default: 30000)
+   * @param {number} options.pollInterval - Poll interval in ms (default: 1000)
+   * @returns {Promise<{request_id: string, status: string}>}
+   */
+  async resize(workspace, diskGb, options = {}) {
+    const existing = await this.findJob(workspace);
+    if (existing && existing.status === 'running') {
+      await this._request('POST', `/api/v1/mags-jobs/${existing.request_id}/sync`);
+      await this._request('POST', `/api/v1/mags-jobs/${existing.request_id}/stop`);
       await new Promise(resolve => setTimeout(resolve, 1000));
+    } else if (existing && existing.status === 'sleeping') {
+      await this._request('POST', `/api/v1/mags-jobs/${existing.request_id}/stop`);
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+
+    return this.new(workspace, { diskGb, timeout: options.timeout, pollInterval: options.pollInterval });
+  }
+
+  /**
+   * Get aggregated usage summary
+   * @param {object} options - Options
+   * @param {number} options.windowDays - Time window in days (default: 30)
+   * @returns {Promise<object>}
+   */
+  async usage(options = {}) {
+    return this._request('GET', '/api/v1/mags-jobs/usage', null, { window_days: options.windowDays || 30 });
+  }
+
+  // ── Workspaces ────────────────────────────────────────────────────
+
+  /**
+   * List all workspaces
+   * @returns {Promise<{workspaces: Array, total: number}>}
+   */
+  async listWorkspaces() {
+    return this._request('GET', '/api/v1/mags-workspaces');
+  }
+
+  /**
+   * Delete a workspace and all its stored data
+   * @param {string} workspaceId - Workspace ID to delete
+   * @returns {Promise<object>}
+   */
+  async deleteWorkspace(workspaceId) {
+    return this._request('DELETE', `/api/v1/mags-workspaces/${workspaceId}`);
+  }
+
+  // ── File uploads ──────────────────────────────────────────────────
+
+  /**
+   * Upload files for use in a job
+   * @param {string[]} filePaths - Array of local file paths
+   * @returns {Promise<string[]>} Array of file IDs
+   */
+  async uploadFiles(filePaths) {
+    const fs = require('fs');
+    const path = require('path');
+    const fileIds = [];
+
+    for (const filePath of filePaths) {
+      const fileName = path.basename(filePath);
+      const fileData = fs.readFileSync(filePath);
+      const boundary = '----MagsBoundary' + Date.now().toString(16);
+
+      const parts = [];
+      parts.push(`--${boundary}\r\n`);
+      parts.push(`Content-Disposition: form-data; name="file"; filename="${fileName}"\r\n`);
+      parts.push(`Content-Type: application/octet-stream\r\n\r\n`);
+      const header = Buffer.from(parts.join(''));
+      const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
+      const body = Buffer.concat([header, fileData, footer]);
+
+      const response = await this._multipartRequest('/api/v1/mags-files', body, boundary);
+      if (response.file_id) {
+        fileIds.push(response.file_id);
+      } else {
+        throw new MagsError(`Failed to upload file: ${fileName}`);
+      }
     }
 
-    throw new Error(`Job ${requestId} timed out after ${timeout}ms`);
+    return fileIds;
+  }
+
+  _multipartRequest(apiPath, body, boundary) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(apiPath, this.apiUrl);
+      const isHttps = url.protocol === 'https:';
+      const lib = isHttps ? https : http;
+
+      const options = {
+        hostname: url.hostname,
+        port: url.port || (isHttps ? 443 : 80),
+        path: url.pathname,
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.apiToken}`,
+          'Content-Type': `multipart/form-data; boundary=${boundary}`,
+          'Content-Length': body.length
+        }
+      };
+
+      const req = lib.request(options, (res) => {
+        let data = '';
+        res.on('data', chunk => data += chunk);
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(data));
+          } catch {
+            resolve(data);
+          }
+        });
+      });
+
+      req.on('error', reject);
+      req.write(body);
+      req.end();
+    });
+  }
+
+  // ── Cron jobs ─────────────────────────────────────────────────────
+
+  /**
+   * Create a cron job
+   * @param {object} options - Cron job options
+   * @param {string} options.name - Cron job name
+   * @param {string} options.cronExpression - Cron expression (e.g., "0 * * * *")
+   * @param {string} options.script - Script to execute
+   * @param {string} options.workspaceId - Workspace ID
+   * @param {object} options.environment - Environment variables
+   * @param {boolean} options.persistent - Keep VM alive
+   * @returns {Promise<object>}
+   */
+  async cronCreate(options) {
+    const payload = {
+      name: options.name,
+      cron_expression: options.cronExpression,
+      script: options.script,
+      persistent: options.persistent || false
+    };
+    if (options.workspaceId) payload.workspace_id = options.workspaceId;
+    if (options.environment) payload.environment = options.environment;
+    return this._request('POST', '/api/v1/mags-cron', payload);
+  }
+
+  /**
+   * List cron jobs
+   * @returns {Promise<{cron_jobs: Array}>}
+   */
+  async cronList() {
+    return this._request('GET', '/api/v1/mags-cron');
+  }
+
+  /**
+   * Get a cron job
+   * @param {string} id - Cron job ID
+   * @returns {Promise<object>}
+   */
+  async cronGet(id) {
+    return this._request('GET', `/api/v1/mags-cron/${id}`);
+  }
+
+  /**
+   * Update a cron job
+   * @param {string} id - Cron job ID
+   * @param {object} updates - Fields to update
+   * @returns {Promise<object>}
+   */
+  async cronUpdate(id, updates) {
+    return this._request('PATCH', `/api/v1/mags-cron/${id}`, updates);
+  }
+
+  /**
+   * Delete a cron job
+   * @param {string} id - Cron job ID
+   * @returns {Promise<object>}
+   */
+  async cronDelete(id) {
+    return this._request('DELETE', `/api/v1/mags-cron/${id}`);
+  }
+
+  // ── URL aliases ───────────────────────────────────────────────────
+
+  /**
+   * Create a stable URL alias for a workspace
+   * @param {string} subdomain - Subdomain for the alias
+   * @param {string} workspaceId - Workspace to point to
+   * @param {string} domain - Domain (default: apps.magpiecloud.com)
+   * @returns {Promise<{id: string, subdomain: string, url: string}>}
+   */
+  async urlAliasCreate(subdomain, workspaceId, domain = 'apps.magpiecloud.com') {
+    return this._request('POST', '/api/v1/mags-url-aliases', {
+      subdomain,
+      workspace_id: workspaceId,
+      domain,
+    });
+  }
+
+  /**
+   * List all URL aliases
+   * @returns {Promise<{aliases: Array, total: number}>}
+   */
+  async urlAliasList() {
+    return this._request('GET', '/api/v1/mags-url-aliases');
+  }
+
+  /**
+   * Delete a URL alias by subdomain
+   * @param {string} subdomain - Subdomain to delete
+   * @returns {Promise<object>}
+   */
+  async urlAliasDelete(subdomain) {
+    return this._request('DELETE', `/api/v1/mags-url-aliases/${subdomain}`);
+  }
+
+  // ── Internal helpers ──────────────────────────────────────────────
+
+  /**
+   * Resolve a job name, workspace ID, or UUID to a request_id
+   * @param {string} nameOrId - Name, workspace ID, or request ID
+   * @returns {Promise<string>} The resolved request_id
+   */
+  async _resolveJobId(nameOrId) {
+    // If it looks like a UUID, use directly
+    if (nameOrId.length >= 32 && nameOrId.includes('-')) {
+      return nameOrId;
+    }
+    const job = await this.findJob(nameOrId);
+    if (!job) throw new MagsError(`No job found for '${nameOrId}'`);
+    return job.request_id || job.id;
   }
 }
 
 module.exports = Mags;
 module.exports.Mags = Mags;
+module.exports.MagsError = MagsError;
 module.exports.default = Mags;

package/nodejs/index.js

@@ -7,25 +7,40 @@ const https = require('https');
 const http = require('http');
 const { URL } = require('url');
 
+class MagsError extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.name = 'MagsError';
+    this.statusCode = statusCode || null;
+  }
+}
+
 class Mags {
   /**
    * Create a Mags client
    * @param {object} options - Configuration options
    * @param {string} options.apiUrl - API endpoint (default: https://api.magpiecloud.com)
    * @param {string} options.apiToken - API token (required, or set MAGS_API_TOKEN env var)
+   * @param {number} options.timeout - Default request timeout in ms (default: 30000)
    */
   constructor(options = {}) {
-    this.apiUrl = options.apiUrl || process.env.MAGS_API_URL || 'https://api.magpiecloud.com';
-    this.apiToken = options.apiToken || process.env.MAGS_API_TOKEN;
+    this.apiUrl = (options.apiUrl || process.env.MAGS_API_URL || 'https://api.magpiecloud.com').replace(/\/+$/, '');
+    this.apiToken = options.apiToken || process.env.MAGS_API_TOKEN || process.env.MAGS_TOKEN;
+    this.timeout = options.timeout || 30000;
 
     if (!this.apiToken) {
-      throw new Error('API token required. Set MAGS_API_TOKEN or pass apiToken option.');
+      throw new MagsError('API token required. Set MAGS_API_TOKEN or pass apiToken option.');
     }
   }
 
-  _request(method, path, body = null) {
+  _request(method, path, body = null, params = null) {
     return new Promise((resolve, reject) => {
       const url = new URL(path, this.apiUrl);
+      if (params) {
+        for (const [k, v] of Object.entries(params)) {
+          url.searchParams.set(k, v);
+        }
+      }
       const isHttps = url.protocol === 'https:';
       const lib = isHttps ? https : http;
 
@@ -37,7 +52,8 @@ class Mags {
         headers: {
           'Authorization': `Bearer ${this.apiToken}`,
           'Content-Type': 'application/json'
-        }
+        },
+        timeout: this.timeout
       };
 
       const req = lib.request(options, (res) => {
@@ -47,66 +63,110 @@ class Mags {
           try {
             const parsed = JSON.parse(data);
             if (res.statusCode >= 400) {
-              reject(new Error(parsed.error || parsed.message || `HTTP ${res.statusCode}`));
+              reject(new MagsError(parsed.error || parsed.message || `HTTP ${res.statusCode}`, res.statusCode));
             } else {
               resolve(parsed);
             }
           } catch {
-            resolve(data);
+            if (res.statusCode >= 400) {
+              reject(new MagsError(data || `HTTP ${res.statusCode}`, res.statusCode));
+            } else {
+              resolve(data);
+            }
           }
         });
       });
 
       req.on('error', reject);
+      req.on('timeout', () => {
+        req.destroy();
+        reject(new MagsError('Request timed out'));
+      });
       if (body) req.write(JSON.stringify(body));
       req.end();
     });
   }
 
+  // ── Jobs ──────────────────────────────────────────────────────────
+
   /**
    * Submit a job for execution
    * @param {string} script - Script to execute
    * @param {object} options - Job options
    * @param {string} options.name - Job name
    * @param {string} options.workspaceId - Persistent workspace ID
+   * @param {string} options.baseWorkspaceId - Read-only base workspace to mount
    * @param {boolean} options.persistent - Keep VM alive after script
+   * @param {boolean} options.noSleep - Never auto-sleep (requires persistent)
    * @param {boolean} options.ephemeral - No workspace/S3 sync (fastest)
    * @param {string} options.startupCommand - Command to run when waking from sleep
    * @param {object} options.environment - Environment variables
    * @param {string[]} options.fileIds - File IDs from uploadFiles()
-   * @returns {Promise<{requestId: string, status: string}>}
+   * @param {number} options.diskGb - Custom disk size in GB (default 2)
+   * @returns {Promise<{request_id: string, status: string}>}
    */
   async run(script, options = {}) {
     if (options.ephemeral && options.workspaceId) {
-      throw new Error('Cannot use ephemeral with workspaceId');
+      throw new MagsError('Cannot use ephemeral with workspaceId');
     }
     if (options.ephemeral && options.persistent) {
-      throw new Error('Cannot use ephemeral with persistent');
+      throw new MagsError('Cannot use ephemeral with persistent');
+    }
+    if (options.noSleep && !options.persistent) {
+      throw new MagsError('noSleep requires persistent=true');
     }
 
     const payload = {
       script,
       type: 'inline',
-      name: options.name,
       persistent: options.persistent || false,
-      startup_command: options.startupCommand,
-      environment: options.environment
     };
 
-    // Only set workspace_id if not ephemeral
-    if (!options.ephemeral) {
-      payload.workspace_id = options.workspaceId;
-    }
+    if (options.noSleep) payload.no_sleep = true;
+    if (options.name) payload.name = options.name;
+    if (!options.ephemeral && options.workspaceId) payload.workspace_id = options.workspaceId;
+    if (options.baseWorkspaceId) payload.base_workspace_id = options.baseWorkspaceId;
+    if (options.startupCommand) payload.startup_command = options.startupCommand;
+    if (options.environment) payload.environment = options.environment;
+    if (options.fileIds && options.fileIds.length > 0) payload.file_ids = options.fileIds;
+    if (options.diskGb) payload.disk_gb = options.diskGb;
+
+    return this._request('POST', '/api/v1/mags-jobs', payload);
+  }
+
+  /**
+   * Run a job and wait for completion
+   * @param {string} script - Script to execute
+   * @param {object} options - Job options (same as run() plus timeout/pollInterval)
+   * @param {number} options.timeout - Timeout in ms (default: 60000)
+   * @param {number} options.pollInterval - Poll interval in ms (default: 1000)
+   * @returns {Promise<{requestId: string, status: string, exitCode: number, durationMs: number, logs: Array}>}
+   */
+  async runAndWait(script, options = {}) {
+    const timeout = options.timeout || 60000;
+    const pollInterval = options.pollInterval || 1000;
+    const result = await this.run(script, options);
+    const requestId = result.request_id;
+
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+      const status = await this.status(requestId);
+
+      if (status.status === 'completed' || status.status === 'error') {
+        const logsResp = await this.logs(requestId);
+        return {
+          requestId,
+          status: status.status,
+          exitCode: status.exit_code,
+          durationMs: status.script_duration_ms,
+          logs: logsResp.logs || []
+        };
+      }
 
-    if (options.fileIds && options.fileIds.length > 0) {
-      payload.file_ids = options.fileIds;
+      await new Promise(resolve => setTimeout(resolve, pollInterval));
     }
 
-    const response = await this._request('POST', '/api/v1/mags-jobs', payload);
-    return {
-      requestId: response.request_id,
-      status: response.status
-    };
+    throw new MagsError(`Job ${requestId} timed out after ${timeout}ms`);
   }
 
   /**
@@ -137,60 +197,262 @@ class Mags {
   async list(options = {}) {
     const page = options.page || 1;
     const pageSize = options.pageSize || 20;
-    return this._request('GET', `/api/v1/mags-jobs?page=${page}&page_size=${pageSize}`);
+    return this._request('GET', `/api/v1/mags-jobs`, null, { page, page_size: pageSize });
   }
 
   /**
-   * Enable URL access for a job
+   * Update a job's settings
    * @param {string} requestId - Job request ID
-   * @param {number} port - Port to expose (default: 8080)
+   * @param {object} options - Settings to update
+   * @param {string} options.startupCommand - Command to run when VM wakes from sleep
+   * @param {boolean} options.noSleep - If true, VM never auto-sleeps. If false, re-enables auto-sleep.
    * @returns {Promise<object>}
    */
-  async enableUrl(requestId, port = 8080) {
-    return this._request('POST', `/api/v1/mags-jobs/${requestId}/access`, { port });
+  async updateJob(requestId, options = {}) {
+    const payload = {};
+    if (options.startupCommand !== undefined) payload.startup_command = options.startupCommand;
+    if (options.noSleep !== undefined) payload.no_sleep = options.noSleep;
+    return this._request('PATCH', `/api/v1/mags-jobs/${requestId}`, payload);
   }
 
   /**
-   * Stop a running job
+   * Enable URL or SSH access for a job
    * @param {string} requestId - Job request ID
+   * @param {number} port - Port to expose (default: 8080, use 22 for SSH)
    * @returns {Promise<object>}
    */
-  async stop(requestId) {
+  async enableAccess(requestId, port = 8080) {
+    return this._request('POST', `/api/v1/mags-jobs/${requestId}/access`, { port });
+  }
+
+  /**
+   * Enable public URL access for a job's VM
+   * @param {string} nameOrId - Job name, workspace ID, or request ID
+   * @param {number} port - Port to expose (default: 8080)
+   * @returns {Promise<object>} Object with url and access details
+   */
+  async url(nameOrId, port = 8080) {
+    const requestId = await this._resolveJobId(nameOrId);
+    const st = await this.status(requestId);
+    const resp = await this.enableAccess(requestId, port);
+    const subdomain = st.subdomain || resp.subdomain;
+    if (subdomain) {
+      resp.url = `https://${subdomain}.apps.magpiecloud.com`;
+    }
+    return resp;
+  }
+
+  /**
+   * Stop a running job. Accepts a job ID, job name, or workspace ID.
+   * @param {string} nameOrId - Job name, workspace ID, or request ID
+   * @returns {Promise<object>}
+   */
+  async stop(nameOrId) {
+    const requestId = await this._resolveJobId(nameOrId);
     return this._request('POST', `/api/v1/mags-jobs/${requestId}/stop`);
   }
 
   /**
-   * Run a job and wait for completion
-   * @param {string} script - Script to execute
-   * @param {object} options - Job options
-   * @param {number} options.timeout - Timeout in ms (default: 60000)
-   * @returns {Promise<{status: string, exitCode: number, logs: Array}>}
+   * Sync a running job's workspace to S3 without stopping the VM
+   * @param {string} requestId - Job request ID
+   * @returns {Promise<object>}
    */
-  async runAndWait(script, options = {}) {
-    const timeout = options.timeout || 60000;
-    const { requestId } = await this.run(script, options);
+  async sync(requestId) {
+    return this._request('POST', `/api/v1/mags-jobs/${requestId}/sync`);
+  }
+
+  /**
+   * Create a new persistent VM workspace and wait until it's running
+   * @param {string} name - Workspace name
+   * @param {object} options - Options
+   * @param {string} options.baseWorkspaceId - Read-only base workspace to mount
+   * @param {number} options.diskGb - Custom disk size in GB
+   * @param {number} options.timeout - Timeout in ms (default: 30000)
+   * @param {number} options.pollInterval - Poll interval in ms (default: 1000)
+   * @returns {Promise<{request_id: string, status: string}>}
+   */
+  async new(name, options = {}) {
+    const timeout = options.timeout || 30000;
+    const pollInterval = options.pollInterval || 1000;
+
+    const result = await this.run('sleep infinity', {
+      workspaceId: name,
+      persistent: true,
+      baseWorkspaceId: options.baseWorkspaceId,
+      diskGb: options.diskGb,
+    });
+    const requestId = result.request_id;
 
     const startTime = Date.now();
     while (Date.now() - startTime < timeout) {
-      const status = await this.status(requestId);
+      const st = await this.status(requestId);
+      if (st.status === 'running' && st.vm_id) {
+        return { request_id: requestId, status: 'running' };
+      }
+      if (st.status === 'completed' || st.status === 'error') {
+        throw new MagsError(`Job ${requestId} ended unexpectedly: ${st.status}`);
+      }
+      await new Promise(resolve => setTimeout(resolve, pollInterval));
+    }
 
-      if (status.status === 'completed' || status.status === 'error') {
-        const logsResp = await this.logs(requestId);
-        return {
-          requestId,
-          status: status.status,
-          exitCode: status.exit_code,
-          durationMs: status.script_duration_ms,
-          logs: logsResp.logs || []
-        };
+    throw new MagsError(`Job ${requestId} did not start within ${timeout}ms`);
+  }
+
+  /**
+   * Find a running or sleeping job by name, workspace ID, or job ID
+   * @param {string} nameOrId - Job name, workspace ID, or request ID
+   * @returns {Promise<object|null>} The job object, or null if not found
+   */
+  async findJob(nameOrId) {
+    const resp = await this.list({ pageSize: 50 });
+    const jobs = resp.jobs || [];
+
+    // Priority 1: exact name match, running/sleeping
+    for (const j of jobs) {
+      if (j.name === nameOrId && (j.status === 'running' || j.status === 'sleeping')) return j;
+    }
+    // Priority 2: workspace_id match, running/sleeping
+    for (const j of jobs) {
+      if (j.workspace_id === nameOrId && (j.status === 'running' || j.status === 'sleeping')) return j;
+    }
+    // Priority 3: exact name match, any status
+    for (const j of jobs) {
+      if (j.name === nameOrId) return j;
+    }
+    // Priority 4: workspace_id match, any status
+    for (const j of jobs) {
+      if (j.workspace_id === nameOrId) return j;
+    }
+
+    return null;
+  }
+
+  /**
+   * Execute a command on an existing running/sleeping VM via SSH
+   * @param {string} nameOrId - Job name, workspace ID, or request ID
+   * @param {string} command - Command to execute
+   * @param {object} options - Options
+   * @param {number} options.timeout - Timeout in ms (default: 30000)
+   * @returns {Promise<{exitCode: number, output: string, stderr: string}>}
+   */
+  async exec(nameOrId, command, options = {}) {
+    const timeout = options.timeout || 30000;
+
+    const job = await this.findJob(nameOrId);
+    if (!job) throw new MagsError(`No running or sleeping VM found for '${nameOrId}'`);
+    if (job.status !== 'running' && job.status !== 'sleeping') {
+      throw new MagsError(`VM for '${nameOrId}' is ${job.status}, needs to be running or sleeping`);
+    }
+
+    const requestId = job.request_id || job.id;
+    const access = await this.enableAccess(requestId, 22);
+
+    if (!access.success || !access.ssh_host) {
+      throw new MagsError(`Failed to enable SSH access: ${access.error || 'unknown error'}`);
+    }
+
+    const { execFileSync, execFile } = require('child_process');
+    const fs = require('fs');
+    const os = require('os');
+    const path = require('path');
+
+    const escaped = command.replace(/'/g, "'\\''");
+    const wrapped =
+      `if [ -d /overlay/bin ]; then ` +
+      `chroot /overlay /bin/sh -l -c 'cd /root 2>/dev/null; ${escaped}'; ` +
+      `else cd /root 2>/dev/null; ${escaped}; fi`;
+
+    let keyFile = null;
+    try {
+      const sshArgs = [
+        '-o', 'StrictHostKeyChecking=no',
+        '-o', 'UserKnownHostsFile=/dev/null',
+        '-o', 'LogLevel=ERROR',
+        '-p', String(access.ssh_port),
+      ];
+
+      if (access.ssh_private_key) {
+        keyFile = path.join(os.tmpdir(), `mags_ssh_${Date.now()}`);
+        fs.writeFileSync(keyFile, access.ssh_private_key, { mode: 0o600 });
+        sshArgs.push('-i', keyFile);
       }
 
+      sshArgs.push(`root@${access.ssh_host}`, wrapped);
+
+      return new Promise((resolve, reject) => {
+        const proc = execFile('ssh', sshArgs, { timeout, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+          if (keyFile) try { fs.unlinkSync(keyFile); } catch {}
+          if (err && err.killed) {
+            reject(new MagsError(`Command timed out after ${timeout}ms`));
+          } else {
+            resolve({
+              exitCode: err ? err.code || 1 : 0,
+              output: stdout,
+              stderr: stderr,
+            });
+          }
+        });
+      });
+    } catch (e) {
+      if (keyFile) try { require('fs').unlinkSync(keyFile); } catch {}
+      throw e;
+    }
+  }
+
+  /**
+   * Resize a workspace's disk. Stops the existing VM, then creates a new one.
+   * @param {string} workspace - Workspace name
+   * @param {number} diskGb - New disk size in GB
+   * @param {object} options - Options
+   * @param {number} options.timeout - Timeout in ms (default: 30000)
+   * @param {number} options.pollInterval - Poll interval in ms (default: 1000)
+   * @returns {Promise<{request_id: string, status: string}>}
+   */
+  async resize(workspace, diskGb, options = {}) {
+    const existing = await this.findJob(workspace);
+    if (existing && existing.status === 'running') {
+      await this._request('POST', `/api/v1/mags-jobs/${existing.request_id}/sync`);
+      await this._request('POST', `/api/v1/mags-jobs/${existing.request_id}/stop`);
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    } else if (existing && existing.status === 'sleeping') {
+      await this._request('POST', `/api/v1/mags-jobs/${existing.request_id}/stop`);
       await new Promise(resolve => setTimeout(resolve, 1000));
     }
 
-    throw new Error(`Job ${requestId} timed out after ${timeout}ms`);
+    return this.new(workspace, { diskGb, timeout: options.timeout, pollInterval: options.pollInterval });
   }
 
+  /**
+   * Get aggregated usage summary
+   * @param {object} options - Options
+   * @param {number} options.windowDays - Time window in days (default: 30)
+   * @returns {Promise<object>}
+   */
+  async usage(options = {}) {
+    return this._request('GET', '/api/v1/mags-jobs/usage', null, { window_days: options.windowDays || 30 });
+  }
+
+  // ── Workspaces ────────────────────────────────────────────────────
+
+  /**
+   * List all workspaces
+   * @returns {Promise<{workspaces: Array, total: number}>}
+   */
+  async listWorkspaces() {
+    return this._request('GET', '/api/v1/mags-workspaces');
+  }
+
+  /**
+   * Delete a workspace and all its stored data
+   * @param {string} workspaceId - Workspace ID to delete
+   * @returns {Promise<object>}
+   */
+  async deleteWorkspace(workspaceId) {
+    return this._request('DELETE', `/api/v1/mags-workspaces/${workspaceId}`);
+  }
+
+  // ── File uploads ──────────────────────────────────────────────────
+
   /**
    * Upload files for use in a job
    * @param {string[]} filePaths - Array of local file paths
@@ -218,7 +480,7 @@ class Mags {
       if (response.file_id) {
         fileIds.push(response.file_id);
       } else {
-        throw new Error(`Failed to upload file: ${fileName}`);
+        throw new MagsError(`Failed to upload file: ${fileName}`);
       }
     }
 
@@ -261,7 +523,7 @@ class Mags {
     });
   }
 
-  // Cron job methods
+  // ── Cron jobs ─────────────────────────────────────────────────────
 
   /**
    * Create a cron job
@@ -270,6 +532,7 @@ class Mags {
    * @param {string} options.cronExpression - Cron expression (e.g., "0 * * * *")
    * @param {string} options.script - Script to execute
    * @param {string} options.workspaceId - Workspace ID
+   * @param {object} options.environment - Environment variables
    * @param {boolean} options.persistent - Keep VM alive
    * @returns {Promise<object>}
    */
@@ -278,9 +541,10 @@ class Mags {
       name: options.name,
       cron_expression: options.cronExpression,
       script: options.script,
-      workspace_id: options.workspaceId,
       persistent: options.persistent || false
     };
+    if (options.workspaceId) payload.workspace_id = options.workspaceId;
+    if (options.environment) payload.environment = options.environment;
     return this._request('POST', '/api/v1/mags-cron', payload);
   }
 
@@ -319,8 +583,60 @@ class Mags {
   async cronDelete(id) {
     return this._request('DELETE', `/api/v1/mags-cron/${id}`);
   }
+
+  // ── URL aliases ───────────────────────────────────────────────────
+
+  /**
+   * Create a stable URL alias for a workspace
+   * @param {string} subdomain - Subdomain for the alias
+   * @param {string} workspaceId - Workspace to point to
+   * @param {string} domain - Domain (default: apps.magpiecloud.com)
+   * @returns {Promise<{id: string, subdomain: string, url: string}>}
+   */
+  async urlAliasCreate(subdomain, workspaceId, domain = 'apps.magpiecloud.com') {
+    return this._request('POST', '/api/v1/mags-url-aliases', {
+      subdomain,
+      workspace_id: workspaceId,
+      domain,
+    });
+  }
+
+  /**
+   * List all URL aliases
+   * @returns {Promise<{aliases: Array, total: number}>}
+   */
+  async urlAliasList() {
+    return this._request('GET', '/api/v1/mags-url-aliases');
+  }
+
+  /**
+   * Delete a URL alias by subdomain
+   * @param {string} subdomain - Subdomain to delete
+   * @returns {Promise<object>}
+   */
+  async urlAliasDelete(subdomain) {
+    return this._request('DELETE', `/api/v1/mags-url-aliases/${subdomain}`);
+  }
+
+  // ── Internal helpers ──────────────────────────────────────────────
+
+  /**
+   * Resolve a job name, workspace ID, or UUID to a request_id
+   * @param {string} nameOrId - Name, workspace ID, or request ID
+   * @returns {Promise<string>} The resolved request_id
+   */
+  async _resolveJobId(nameOrId) {
+    // If it looks like a UUID, use directly
+    if (nameOrId.length >= 32 && nameOrId.includes('-')) {
+      return nameOrId;
+    }
+    const job = await this.findJob(nameOrId);
+    if (!job) throw new MagsError(`No job found for '${nameOrId}'`);
+    return job.request_id || job.id;
+  }
 }
 
 module.exports = Mags;
 module.exports.Mags = Mags;
+module.exports.MagsError = MagsError;
 module.exports.default = Mags;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magpiecloud/mags",
-  "version": "1.8.8",
+  "version": "1.8.10",
   "description": "Mags CLI - Execute scripts on Magpie's instant VM infrastructure",
   "main": "index.js",
   "bin": {
@@ -20,11 +20,7 @@
   ],
   "author": "Magpie Cloud",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/magpiecloud/mags"
-  },
-  "homepage": "https://magpiecloud.com/docs/mags",
+  "homepage": "https://mags.run",
   "engines": {
     "node": ">=14.0.0"
   }