computesdk 1.12.1 → 1.15.0

package/dist/index.js

@@ -1388,10 +1388,15 @@ var Server = class {
     this.stopHandler = handlers.stop;
     this.restartHandler = handlers.restart;
     this.updateStatusHandler = handlers.updateStatus;
+    this.logsHandler = handlers.logs;
   }
   /**
    * Start a new managed server with optional supervisor settings
    *
+   * **Install Phase:**
+   * If `install` is provided, it runs blocking before `start` (e.g., "npm install").
+   * The server status will be `installing` during this phase.
+   *
    * **Restart Policies:**
    * - `never` (default): No automatic restart on exit
    * - `on-failure`: Restart only on non-zero exit code
@@ -1409,14 +1414,15 @@ var Server = class {
    * // Basic server
    * const server = await sandbox.server.start({
    *   slug: 'web',
-   *   command: 'npm run dev',
+   *   start: 'npm run dev',
    *   path: '/app',
    * });
    *
-   * // With supervisor settings
+   * // With install command
    * const server = await sandbox.server.start({
    *   slug: 'api',
-   *   command: 'node server.js',
+   *   install: 'npm install',
+   *   start: 'node server.js',
    *   environment: { NODE_ENV: 'production' },
    *   restart_policy: 'always',
    *   max_restarts: 0, // unlimited
@@ -1468,6 +1474,29 @@ var Server = class {
   async updateStatus(slug, status) {
     await this.updateStatusHandler(slug, status);
   }
+  /**
+   * Retrieve captured output (logs) for a managed server
+   * @param slug - The server slug
+   * @param options - Options for log retrieval
+   * @returns Server logs info
+   *
+   * @example
+   * ```typescript
+   * // Get combined logs (default)
+   * const logs = await sandbox.server.logs('api');
+   * console.log(logs.logs);
+   *
+   * // Get only stdout
+   * const stdout = await sandbox.server.logs('api', { stream: 'stdout' });
+   *
+   * // Get only stderr
+   * const stderr = await sandbox.server.logs('api', { stream: 'stderr' });
+   * ```
+   */
+  async logs(slug, options) {
+    const response = await this.logsHandler(slug, options);
+    return response.data;
+  }
 };
 
 // src/client/resources/watcher.ts
@@ -1898,6 +1927,88 @@ var Child = class {
   }
 };
 
+// src/client/resources/overlay.ts
+var Overlay = class {
+  constructor(handlers) {
+    this.createHandler = handlers.create;
+    this.listHandler = handlers.list;
+    this.retrieveHandler = handlers.retrieve;
+    this.destroyHandler = handlers.destroy;
+  }
+  /**
+   * Create a new overlay from a template directory
+   *
+   * The overlay copies files from the source directory into the target path
+   * for better isolation. Heavy directories (node_modules, .venv, etc.) are
+   * copied in the background. Use the `ignore` option to exclude files/directories.
+   *
+   * @param options - Overlay creation options
+   * @param options.source - Absolute path to source directory
+   * @param options.target - Relative path in sandbox
+   * @param options.ignore - Glob patterns to ignore (e.g., ["node_modules", "*.log"])
+   * @returns Overlay info with copy status
+   */
+  async create(options) {
+    const response = await this.createHandler(options);
+    return this.toOverlayInfo(response);
+  }
+  /**
+   * List all overlays for the current sandbox
+   * @returns Array of overlay info
+   */
+  async list() {
+    const response = await this.listHandler();
+    return response.overlays.map((o) => this.toOverlayInfo(o));
+  }
+  /**
+   * Retrieve a specific overlay by ID
+   *
+   * Useful for polling the copy status of an overlay.
+   *
+   * @param id - Overlay ID
+   * @returns Overlay info
+   */
+  async retrieve(id) {
+    const response = await this.retrieveHandler(id);
+    return this.toOverlayInfo(response);
+  }
+  /**
+   * Destroy (delete) an overlay
+   * @param id - Overlay ID
+   */
+  async destroy(id) {
+    return this.destroyHandler(id);
+  }
+  /**
+   * Convert API response to OverlayInfo
+   */
+  toOverlayInfo(response) {
+    return {
+      id: response.id,
+      source: response.source,
+      target: response.target,
+      createdAt: response.created_at,
+      stats: {
+        copiedFiles: response.stats.copied_files,
+        copiedDirs: response.stats.copied_dirs,
+        skipped: response.stats.skipped
+      },
+      copyStatus: this.validateCopyStatus(response.copy_status),
+      copyError: response.copy_error
+    };
+  }
+  /**
+   * Validate and return copy status, defaulting to 'pending' for unknown values
+   */
+  validateCopyStatus(status) {
+    const validStatuses = ["pending", "in_progress", "complete", "failed"];
+    if (validStatuses.includes(status)) {
+      return status;
+    }
+    return "pending";
+  }
+};
+
 // src/client/types.ts
 var CommandExitError = class extends Error {
   constructor(result) {
@@ -1992,7 +2103,13 @@ var Sandbox = class {
       },
       remove: async (path) => {
         await this.deleteFile(path);
-      }
+      },
+      overlay: new Overlay({
+        create: async (options) => this.createOverlay(options),
+        list: async () => this.listOverlays(),
+        retrieve: async (id) => this.getOverlay(id),
+        destroy: async (id) => this.deleteOverlay(id)
+      })
     };
     this.terminal = new Terminal({
       create: async (options) => this.createTerminal(options),
@@ -2037,7 +2154,8 @@ var Sandbox = class {
       restart: async (slug) => this.restartServer(slug),
       updateStatus: async (slug, status) => {
         await this.updateServerStatus(slug, status);
-      }
+      },
+      logs: async (slug, options) => this.getServerLogs(slug, options)
     });
     this.watcher = new Watcher({
       create: async (path, options) => this.createWatcher(path, options),
@@ -2477,6 +2595,63 @@ API request failed (${response.status}): ${error}`
     });
   }
   // ============================================================================
+  // Filesystem Overlays
+  // ============================================================================
+  /**
+   * Create a new filesystem overlay from a template directory
+   *
+   * Overlays enable instant sandbox setup by symlinking template files first,
+   * then copying heavy directories (node_modules, .venv, etc.) in the background.
+   *
+   * @param options - Overlay creation options
+   * @param options.source - Absolute path to source directory (template)
+   * @param options.target - Relative path in sandbox where overlay will be mounted
+   * @returns Overlay response with copy status
+   *
+   * @example
+   * ```typescript
+   * // Prefer using sandbox.filesystem.overlay.create() for camelCase response
+   * const overlay = await sandbox.filesystem.overlay.create({
+   *   source: '/templates/nextjs',
+   *   target: 'project',
+   * });
+   * console.log(overlay.copyStatus); // 'pending' | 'in_progress' | 'complete' | 'failed'
+   * ```
+   */
+  async createOverlay(options) {
+    return this.request("/filesystem/overlays", {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /**
+   * List all filesystem overlays for the current sandbox
+   * @returns List of overlays with their copy status
+   */
+  async listOverlays() {
+    return this.request("/filesystem/overlays");
+  }
+  /**
+   * Get a specific filesystem overlay by ID
+   *
+   * Useful for polling the copy status of an overlay.
+   *
+   * @param id - Overlay ID
+   * @returns Overlay details with current copy status
+   */
+  async getOverlay(id) {
+    return this.request(`/filesystem/overlays/${id}`);
+  }
+  /**
+   * Delete a filesystem overlay
+   * @param id - Overlay ID
+   */
+  async deleteOverlay(id) {
+    return this.request(`/filesystem/overlays/${id}`, {
+      method: "DELETE"
+    });
+  }
+  // ============================================================================
   // Terminal Management
   // ============================================================================
   /**
@@ -2825,7 +3000,8 @@ API request failed (${response.status}): ${error}`
    *
    * @param options - Server configuration
    * @param options.slug - Unique server identifier
-   * @param options.command - Command to start the server
+   * @param options.install - Install command (optional, runs blocking before start, e.g., "npm install")
+   * @param options.start - Command to start the server (e.g., "npm run dev")
    * @param options.path - Working directory (optional)
    * @param options.env_file - Path to .env file relative to path (optional)
    * @param options.environment - Inline environment variables (merged with env_file if both provided)
@@ -2839,14 +3015,15 @@ API request failed (${response.status}): ${error}`
    * // Basic server
    * await sandbox.startServer({
    *   slug: 'web',
-   *   command: 'npm run dev',
+   *   start: 'npm run dev',
    *   path: '/app',
    * });
    *
-   * // With supervisor settings
+   * // With install command and supervisor settings
    * await sandbox.startServer({
    *   slug: 'api',
-   *   command: 'node server.js',
+   *   install: 'npm install',
+   *   start: 'node server.js',
    *   path: '/app',
    *   environment: { NODE_ENV: 'production', PORT: '3000' },
    *   restart_policy: 'on-failure',
@@ -2893,6 +3070,21 @@ API request failed (${response.status}): ${error}`
       }
     );
   }
+  /**
+   * Get logs for a managed server
+   * @param slug - Server slug
+   * @param options - Options for log retrieval
+   */
+  async getServerLogs(slug, options) {
+    const params = new URLSearchParams();
+    if (options?.stream) {
+      params.set("stream", options.stream);
+    }
+    const queryString = params.toString();
+    return this.request(
+      `/servers/${encodeURIComponent(slug)}/logs${queryString ? `?${queryString}` : ""}`
+    );
+  }
   /**
    * Update server status (internal use)
    * @param slug - Server slug
@@ -3174,7 +3366,9 @@ var PROVIDER_HEADERS = {
     tokenSecret: "X-Modal-Token-Secret"
   },
   railway: {
-    apiToken: "X-Railway-API-Token"
+    apiToken: "X-Railway-API-Key",
+    projectId: "X-Railway-Project-ID",
+    environmentId: "X-Railway-Environment-ID"
   },
   daytona: {
     apiKey: "X-Daytona-API-Key"