@magpiecloud/mags 1.5.1 → 1.6.0

package/nodejs/index.js

@@ -0,0 +1,326 @@
+/**
+ * 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 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)
+   */
+  constructor(options = {}) {
+    this.apiUrl = options.apiUrl || process.env.MAGS_API_URL || 'https://api.magpiecloud.com';
+    this.apiToken = options.apiToken || process.env.MAGS_API_TOKEN;
+
+    if (!this.apiToken) {
+      throw new Error('API token required. Set MAGS_API_TOKEN or pass apiToken option.');
+    }
+  }
+
+  _request(method, path, body = null) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(path, 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 + url.search,
+        method,
+        headers: {
+          'Authorization': `Bearer ${this.apiToken}`,
+          'Content-Type': 'application/json'
+        }
+      };
+
+      const req = lib.request(options, (res) => {
+        let data = '';
+        res.on('data', chunk => data += chunk);
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(data);
+            if (res.statusCode >= 400) {
+              reject(new Error(parsed.error || parsed.message || `HTTP ${res.statusCode}`));
+            } else {
+              resolve(parsed);
+            }
+          } catch {
+            resolve(data);
+          }
+        });
+      });
+
+      req.on('error', reject);
+      if (body) req.write(JSON.stringify(body));
+      req.end();
+    });
+  }
+
+  /**
+   * 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 {boolean} options.persistent - Keep VM alive after script
+   * @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}>}
+   */
+  async run(script, options = {}) {
+    if (options.ephemeral && options.workspaceId) {
+      throw new Error('Cannot use ephemeral with workspaceId');
+    }
+    if (options.ephemeral && options.persistent) {
+      throw new Error('Cannot use ephemeral with persistent');
+    }
+
+    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.fileIds && options.fileIds.length > 0) {
+      payload.file_ids = options.fileIds;
+    }
+
+    const response = await this._request('POST', '/api/v1/mags-jobs', payload);
+    return {
+      requestId: response.request_id,
+      status: response.status
+    };
+  }
+
+  /**
+   * Get job status
+   * @param {string} requestId - Job request ID
+   * @returns {Promise<object>}
+   */
+  async status(requestId) {
+    return this._request('GET', `/api/v1/mags-jobs/${requestId}/status`);
+  }
+
+  /**
+   * Get job logs
+   * @param {string} requestId - Job request ID
+   * @returns {Promise<{logs: Array}>}
+   */
+  async logs(requestId) {
+    return this._request('GET', `/api/v1/mags-jobs/${requestId}/logs`);
+  }
+
+  /**
+   * List recent jobs
+   * @param {object} options - Pagination options
+   * @param {number} options.page - Page number (default: 1)
+   * @param {number} options.pageSize - Page size (default: 20)
+   * @returns {Promise<{jobs: Array, total: number}>}
+   */
+  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}`);
+  }
+
+  /**
+   * Enable URL access for a job
+   * @param {string} requestId - Job request ID
+   * @param {number} port - Port to expose (default: 8080)
+   * @returns {Promise<object>}
+   */
+  async enableUrl(requestId, port = 8080) {
+    return this._request('POST', `/api/v1/mags-jobs/${requestId}/access`, { port });
+  }
+
+  /**
+   * Stop a running job
+   * @param {string} requestId - Job request ID
+   * @returns {Promise<object>}
+   */
+  async stop(requestId) {
+    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}>}
+   */
+  async runAndWait(script, options = {}) {
+    const timeout = options.timeout || 60000;
+    const { requestId } = await this.run(script, options);
+
+    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, 1000));
+    }
+
+    throw new Error(`Job ${requestId} timed out after ${timeout}ms`);
+  }
+
+  /**
+   * 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 Error(`Failed to upload file: ${fileName}`);
+      }
+    }
+
+    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 job methods
+
+  /**
+   * 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 {boolean} options.persistent - Keep VM alive
+   * @returns {Promise<object>}
+   */
+  async cronCreate(options) {
+    const payload = {
+      name: options.name,
+      cron_expression: options.cronExpression,
+      script: options.script,
+      workspace_id: options.workspaceId,
+      persistent: options.persistent || false
+    };
+    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}`);
+  }
+}
+
+module.exports = Mags;
+module.exports.Mags = Mags;
+module.exports.default = Mags;

package/nodejs/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@magpiecloud/mags",
+  "version": "1.5.1",
+  "description": "Mags CLI - Execute scripts on Magpie's instant VM infrastructure",
+  "main": "index.js",
+  "bin": {
+    "mags": "./bin/mags.js"
+  },
+  "scripts": {
+    "test": "node bin/mags.js --help"
+  },
+  "keywords": [
+    "magpie",
+    "mags",
+    "vm",
+    "microvm",
+    "cloud",
+    "serverless",
+    "execution",
+    "cli",
+    "claude",
+    "claude-code"
+  ],
+  "author": "Magpie Cloud",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/magpiecloud/mags"
+  },
+  "homepage": "https://mags.run",
+  "bugs": {
+    "url": "https://github.com/magpiecloud/mags/issues"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "index.js",
+    "bin/mags.js",
+    "README.md"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magpiecloud/mags",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Mags CLI - Execute scripts on Magpie's instant VM infrastructure",
   "main": "index.js",
   "bin": {
@@ -16,10 +16,7 @@
     "microvm",
     "cloud",
     "serverless",
-    "execution",
-    "cli",
-    "claude",
-    "claude-code"
+    "execution"
   ],
   "author": "Magpie Cloud",
   "license": "MIT",
@@ -27,16 +24,8 @@
     "type": "git",
     "url": "https://github.com/magpiecloud/mags"
   },
-  "homepage": "https://mags.run",
-  "bugs": {
-    "url": "https://github.com/magpiecloud/mags/issues"
-  },
+  "homepage": "https://magpiecloud.com/docs/mags",
   "engines": {
     "node": ">=14.0.0"
-  },
-  "files": [
-    "index.js",
-    "bin/mags.js",
-    "README.md"
-  ]
+  }
 }