@daytonaio/sdk 0.9.2 → 0.10.1

package/dist/Process.d.ts

@@ -1,67 +1,217 @@
-import { Command, ExecuteResponse, Session, SessionExecuteRequest, SessionExecuteResponse, ToolboxApi, Workspace } from '@daytonaio/api-client';
-import { WorkspaceCodeToolbox } from './Workspace';
 /**
- * Handles process and code execution within a workspace
- * @class Process
+ * The Daytona SDK provides powerful process and code execution capabilities through
+ * the `process` module in Sandboxes. This guide covers all available process operations
+ * and best practices.
+ *
+ * @module Process
+ *
+ * @example
+ * // Execute a shell command
+ * const response = await workspace.process.executeCommand('ls -la');
+ * console.log(response.result);
+ *
+ * // Run TypeScript code
+ * const response = await workspace.process.codeRun('console.log("Hello, World!")');
+ * console.log(response.result);
+ *
+ * @example
+ * // Using interactive sessions
+ * // Create a new session
+ * const sessionId = 'my-session';
+ * await workspace.process.createSession(sessionId);
+ *
+ * // Execute commands in the session
+ * const response = await workspace.process.executeSessionCommand(sessionId, {
+ *   command: 'cd /workspace'
+ * });
+ *
+ * const response2 = await workspace.process.executeSessionCommand(sessionId, {
+ *   command: 'pwd'
+ * });
+ * console.log(response2.result);  // Should print "/workspace"
+ *
+ * // Clean up
+ * await workspace.process.deleteSession(sessionId);
  */
+import { Command, ExecuteResponse, Session, SessionExecuteRequest, SessionExecuteResponse, ToolboxApi } from '@daytonaio/api-client';
+import { WorkspaceCodeToolbox, WorkspaceInstance } from './Workspace';
+/**
+ * Parameters for code execution
+ */
+export declare class CodeRunParams {
+    /**
+     * Command line arguments
+     */
+    argv?: string[];
+    /**
+     * Environment variables
+     */
+    env?: Record<string, string>;
+}
 export declare class Process {
     private readonly codeToolbox;
     private readonly toolboxApi;
     private readonly instance;
-    constructor(codeToolbox: WorkspaceCodeToolbox, toolboxApi: ToolboxApi, instance: Workspace);
+    constructor(codeToolbox: WorkspaceCodeToolbox, toolboxApi: ToolboxApi, instance: WorkspaceInstance);
     /**
-     * Executes a shell command in the workspace
-     * @param {string} command - Command to execute
-     * @returns {Promise<ExecuteResponse>} Command execution results
+     * Executes a shell command in the Sandbox.
+     *
+     * @param {string} command - Shell command to execute
+     * @param {string} [cwd] - Working directory for command execution. If not specified, uses the Sandbox root directory
+     * @param {number} [timeout] - Maximum time in seconds to wait for the command to complete. 0 means wait indefinitely.
+     * @returns {Promise<ExecuteResponse>} Command execution results containing:
+     *                                    - exitCode: The command's exit status
+     *                                    - result: Standard output from the command
+     *
+     * @example
+     * // Simple command
+     * const response = await process.executeCommand('echo "Hello"');
+     * console.log(response.result);  // Prints: Hello
+     *
+     * @example
+     * // Command with working directory
+     * const result = await process.executeCommand('ls', '/workspace/src');
+     *
+     * @example
+     * // Command with timeout
+     * const result = await process.executeCommand('sleep 10', undefined, 5);
      */
     executeCommand(command: string, cwd?: string, timeout?: number): Promise<ExecuteResponse>;
     /**
-     * Executes code in the workspace using the appropriate language runtime
+     * Executes code in the Sandbox using the appropriate language runtime.
+     *
      * @param {string} code - Code to execute
-     * @returns {Promise<ExecuteResponse>} Code execution results
+     * @param {CodeRunParams} params - Parameters for code execution
+     * @returns {Promise<ExecuteResponse>} Code execution results containing:
+     *                                    - exitCode: The execution's exit status
+     *                                    - result: Standard output from the code
+     *
+     * @example
+     * // Run TypeScript code
+     * const response = await process.codeRun(`
+     *   const x = 10;
+     *   const y = 20;
+     *   console.log(\`Sum: \${x + y}\`);
+     * `);
+     * console.log(response.result);  // Prints: Sum: 30
      */
-    codeRun(code: string): Promise<ExecuteResponse>;
+    codeRun(code: string, params?: CodeRunParams, timeout?: number): Promise<ExecuteResponse>;
     /**
-     * Creates a new exec session in the workspace
-     * @param {string} sessionId - Unique identifier for the session
-     * @returns {Promise<ExecuteResponse>} Code execution results
+     * Creates a new long-running background session in the Sandbox.
+     *
+     * Sessions are background processes that maintain state between commands, making them ideal for
+     * scenarios requiring multiple related commands or persistent environment setup. You can run
+     * long-running commands and monitor process status.
+     *
+     * @param {string} sessionId - Unique identifier for the new session
+     * @returns {Promise<void>}
+     *
+     * @example
+     * // Create a new session
+     * const sessionId = 'my-session';
+     * await process.createSession(sessionId);
+     * const session = await process.getSession(sessionId);
+     * // Do work...
+     * await process.deleteSession(sessionId);
      */
     createSession(sessionId: string): Promise<void>;
     /**
-     * Executes a command in the session
-     * @param {string} sessionId - Unique identifier for the session
-     * @param {SessionExecuteRequest} req - Command to execute and async flag
-     * @returns {Promise<SessionExecuteResponse>} Command execution results
+     * Get a session in the workspace.
+     *
+     * @param {string} sessionId - Unique identifier of the session to retrieve
+     * @returns {Promise<Session>} Session information including:
+     *                            - sessionId: The session's unique identifier
+     *                            - commands: List of commands executed in the session
+     *
+     * @example
+     * const session = await process.getSession('my-session');
+     * session.commands.forEach(cmd => {
+     *   console.log(`Command: ${cmd.command}`);
+     * });
      */
-    executeSessionCommand(sessionId: string, req: SessionExecuteRequest): Promise<SessionExecuteResponse>;
+    getSession(sessionId: string): Promise<Session>;
     /**
-     * Gets the logs for a command in the session
-     * @param {string} sessionId - Unique identifier for the session
-     * @param {string} commandId - Unique identifier for the command
-     * @returns {Promise<string>} Command logs
+     * Gets information about a specific command executed in a session.
+     *
+     * @param {string} sessionId - Unique identifier of the session
+     * @param {string} commandId - Unique identifier of the command
+     * @returns {Promise<Command>} Command information including:
+     *                            - id: The command's unique identifier
+     *                            - command: The executed command string
+     *                            - exitCode: Command's exit status (if completed)
+     *
+     * @example
+     * const cmd = await process.getSessionCommand('my-session', 'cmd-123');
+     * if (cmd.exitCode === 0) {
+     *   console.log(`Command ${cmd.command} completed successfully`);
+     * }
      */
-    getSessionCommandLogs(sessionId: string, commandId: string): Promise<string>;
+    getSessionCommand(sessionId: string, commandId: string): Promise<Command>;
     /**
-     * Gets the session
-     * @param {string} sessionId - Unique identifier for the session
-     * @returns {Promise<Session>} Session
+     * Executes a command in an existing session.
+     *
+     * @param {string} sessionId - Unique identifier of the session to use
+     * @param {SessionExecuteRequest} req - Command execution request containing:
+     *                                     - command: The command to execute
+     *                                     - async: Whether to execute asynchronously
+     * @param {number} timeout - Timeout in seconds
+     * @returns {Promise<SessionExecuteResponse>} Command execution results containing:
+     *                                           - cmdId: Unique identifier for the executed command
+     *                                           - output: Command output (if synchronous execution)
+     *                                           - exitCode: Command exit status (if synchronous execution)
+     *
+     * @example
+     * // Execute commands in sequence, maintaining state
+     * const sessionId = 'my-session';
+     *
+     * // Change directory
+     * await process.executeSessionCommand(sessionId, {
+     *   command: 'cd /workspace'
+     * });
+     *
+     * // Run command in new directory
+     * const result = await process.executeSessionCommand(sessionId, {
+     *   command: 'pwd'
+     * });
+     * console.log(result.output);  // Prints: /workspace
      */
-    getSession(sessionId: string): Promise<Session>;
+    executeSessionCommand(sessionId: string, req: SessionExecuteRequest, timeout?: number): Promise<SessionExecuteResponse>;
     /**
-     * Gets the session command
-     * @param {string} sessionId - Unique identifier for the session
-     * @param {string} commandId - Unique identifier for the command
-     * @returns {Promise<Command>} Session command
+     * Get the logs for a command executed in a session.
+     *
+     * @param {string} sessionId - Unique identifier of the session
+     * @param {string} commandId - Unique identifier of the command
+     * @returns {Promise<string>} Command logs
+     *
+     * @example
+     * const logs = await process.getSessionCommandLogs('my-session', 'cmd-123');
+     * console.log('Command output:', logs);
      */
-    getSessionCommand(sessionId: string, commandId: string): Promise<Command>;
+    getSessionCommandLogs(sessionId: string, commandId: string): Promise<string>;
     /**
-     * Lists all sessions in the workspace
-     * @returns {Promise<Session[]>} List of sessions
+     * Lists all active sessions in the Sandbox.
+     *
+     * @returns {Promise<Session[]>} Array of active sessions
+     *
+     * @example
+     * const sessions = await process.listSessions();
+     * sessions.forEach(session => {
+     *   console.log(`Session ${session.sessionId}:`);
+     *   session.commands.forEach(cmd => {
+     *     console.log(`- ${cmd.command} (${cmd.exitCode})`);
+     *   });
+     * });
      */
     listSessions(): Promise<Session[]>;
     /**
-     * Deletes a session in the workspace
-     * @param {string} sessionId - Unique identifier for the session
+     * Delete a session from the Sandbox.
+     *
+     * @param {string} sessionId - Unique identifier of the session to delete
+     * @returns {Promise<void>}
+     *
+     * @example
+     * // Clean up a completed session
+     * await process.deleteSession('my-session');
      */
     deleteSession(sessionId: string): Promise<void>;
 }

package/dist/Process.js

@@ -1,10 +1,47 @@
 "use strict";
+/**
+ * The Daytona SDK provides powerful process and code execution capabilities through
+ * the `process` module in Sandboxes. This guide covers all available process operations
+ * and best practices.
+ *
+ * @module Process
+ *
+ * @example
+ * // Execute a shell command
+ * const response = await workspace.process.executeCommand('ls -la');
+ * console.log(response.result);
+ *
+ * // Run TypeScript code
+ * const response = await workspace.process.codeRun('console.log("Hello, World!")');
+ * console.log(response.result);
+ *
+ * @example
+ * // Using interactive sessions
+ * // Create a new session
+ * const sessionId = 'my-session';
+ * await workspace.process.createSession(sessionId);
+ *
+ * // Execute commands in the session
+ * const response = await workspace.process.executeSessionCommand(sessionId, {
+ *   command: 'cd /workspace'
+ * });
+ *
+ * const response2 = await workspace.process.executeSessionCommand(sessionId, {
+ *   command: 'pwd'
+ * });
+ * console.log(response2.result);  // Should print "/workspace"
+ *
+ * // Clean up
+ * await workspace.process.deleteSession(sessionId);
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Process = void 0;
+exports.Process = exports.CodeRunParams = void 0;
 /**
- * Handles process and code execution within a workspace
- * @class Process
+ * Parameters for code execution
  */
+class CodeRunParams {
+}
+exports.CodeRunParams = CodeRunParams;
 class Process {
     constructor(codeToolbox, toolboxApi, instance) {
         this.codeToolbox = codeToolbox;
@@ -12,9 +49,27 @@ class Process {
         this.instance = instance;
     }
     /**
-     * Executes a shell command in the workspace
-     * @param {string} command - Command to execute
-     * @returns {Promise<ExecuteResponse>} Command execution results
+     * Executes a shell command in the Sandbox.
+     *
+     * @param {string} command - Shell command to execute
+     * @param {string} [cwd] - Working directory for command execution. If not specified, uses the Sandbox root directory
+     * @param {number} [timeout] - Maximum time in seconds to wait for the command to complete. 0 means wait indefinitely.
+     * @returns {Promise<ExecuteResponse>} Command execution results containing:
+     *                                    - exitCode: The command's exit status
+     *                                    - result: Standard output from the command
+     *
+     * @example
+     * // Simple command
+     * const response = await process.executeCommand('echo "Hello"');
+     * console.log(response.result);  // Prints: Hello
+     *
+     * @example
+     * // Command with working directory
+     * const result = await process.executeCommand('ls', '/workspace/src');
+     *
+     * @example
+     * // Command with timeout
+     * const result = await process.executeCommand('sleep 10', undefined, 5);
      */
     async executeCommand(command, cwd, timeout) {
         const response = await this.toolboxApi.executeCommand(this.instance.id, {
@@ -25,21 +80,45 @@ class Process {
         return response.data;
     }
     /**
-     * Executes code in the workspace using the appropriate language runtime
+     * Executes code in the Sandbox using the appropriate language runtime.
+     *
      * @param {string} code - Code to execute
-     * @returns {Promise<ExecuteResponse>} Code execution results
+     * @param {CodeRunParams} params - Parameters for code execution
+     * @returns {Promise<ExecuteResponse>} Code execution results containing:
+     *                                    - exitCode: The execution's exit status
+     *                                    - result: Standard output from the code
+     *
+     * @example
+     * // Run TypeScript code
+     * const response = await process.codeRun(`
+     *   const x = 10;
+     *   const y = 20;
+     *   console.log(\`Sum: \${x + y}\`);
+     * `);
+     * console.log(response.result);  // Prints: Sum: 30
      */
-    async codeRun(code) {
-        const runCommand = this.codeToolbox.getRunCommand(code);
-        const response = await this.toolboxApi.executeCommand(this.instance.id, {
-            command: runCommand,
-        });
-        return response.data;
+    async codeRun(code, params, timeout) {
+        const runCommand = this.codeToolbox.getRunCommand(code, params);
+        const response = await this.executeCommand(runCommand, undefined, timeout);
+        return response;
     }
     /**
-     * Creates a new exec session in the workspace
-     * @param {string} sessionId - Unique identifier for the session
-     * @returns {Promise<ExecuteResponse>} Code execution results
+     * Creates a new long-running background session in the Sandbox.
+     *
+     * Sessions are background processes that maintain state between commands, making them ideal for
+     * scenarios requiring multiple related commands or persistent environment setup. You can run
+     * long-running commands and monitor process status.
+     *
+     * @param {string} sessionId - Unique identifier for the new session
+     * @returns {Promise<void>}
+     *
+     * @example
+     * // Create a new session
+     * const sessionId = 'my-session';
+     * await process.createSession(sessionId);
+     * const session = await process.getSession(sessionId);
+     * // Do work...
+     * await process.deleteSession(sessionId);
      */
     async createSession(sessionId) {
         await this.toolboxApi.createSession(this.instance.id, {
@@ -47,55 +126,117 @@ class Process {
         });
     }
     /**
-     * Executes a command in the session
-     * @param {string} sessionId - Unique identifier for the session
-     * @param {SessionExecuteRequest} req - Command to execute and async flag
-     * @returns {Promise<SessionExecuteResponse>} Command execution results
+     * Get a session in the workspace.
+     *
+     * @param {string} sessionId - Unique identifier of the session to retrieve
+     * @returns {Promise<Session>} Session information including:
+     *                            - sessionId: The session's unique identifier
+     *                            - commands: List of commands executed in the session
+     *
+     * @example
+     * const session = await process.getSession('my-session');
+     * session.commands.forEach(cmd => {
+     *   console.log(`Command: ${cmd.command}`);
+     * });
      */
-    async executeSessionCommand(sessionId, req) {
-        const response = await this.toolboxApi.executeSessionCommand(this.instance.id, sessionId, req);
+    async getSession(sessionId) {
+        const response = await this.toolboxApi.getSession(this.instance.id, sessionId);
         return response.data;
     }
     /**
-     * Gets the logs for a command in the session
-     * @param {string} sessionId - Unique identifier for the session
-     * @param {string} commandId - Unique identifier for the command
-     * @returns {Promise<string>} Command logs
+     * Gets information about a specific command executed in a session.
+     *
+     * @param {string} sessionId - Unique identifier of the session
+     * @param {string} commandId - Unique identifier of the command
+     * @returns {Promise<Command>} Command information including:
+     *                            - id: The command's unique identifier
+     *                            - command: The executed command string
+     *                            - exitCode: Command's exit status (if completed)
+     *
+     * @example
+     * const cmd = await process.getSessionCommand('my-session', 'cmd-123');
+     * if (cmd.exitCode === 0) {
+     *   console.log(`Command ${cmd.command} completed successfully`);
+     * }
      */
-    async getSessionCommandLogs(sessionId, commandId) {
-        const response = await this.toolboxApi.getSessionCommandLogs(this.instance.id, sessionId, commandId);
+    async getSessionCommand(sessionId, commandId) {
+        const response = await this.toolboxApi.getSessionCommand(this.instance.id, sessionId, commandId);
         return response.data;
     }
     /**
-     * Gets the session
-     * @param {string} sessionId - Unique identifier for the session
-     * @returns {Promise<Session>} Session
+     * Executes a command in an existing session.
+     *
+     * @param {string} sessionId - Unique identifier of the session to use
+     * @param {SessionExecuteRequest} req - Command execution request containing:
+     *                                     - command: The command to execute
+     *                                     - async: Whether to execute asynchronously
+     * @param {number} timeout - Timeout in seconds
+     * @returns {Promise<SessionExecuteResponse>} Command execution results containing:
+     *                                           - cmdId: Unique identifier for the executed command
+     *                                           - output: Command output (if synchronous execution)
+     *                                           - exitCode: Command exit status (if synchronous execution)
+     *
+     * @example
+     * // Execute commands in sequence, maintaining state
+     * const sessionId = 'my-session';
+     *
+     * // Change directory
+     * await process.executeSessionCommand(sessionId, {
+     *   command: 'cd /workspace'
+     * });
+     *
+     * // Run command in new directory
+     * const result = await process.executeSessionCommand(sessionId, {
+     *   command: 'pwd'
+     * });
+     * console.log(result.output);  // Prints: /workspace
      */
-    async getSession(sessionId) {
-        const response = await this.toolboxApi.getSession(this.instance.id, sessionId);
+    async executeSessionCommand(sessionId, req, timeout) {
+        const response = await this.toolboxApi.executeSessionCommand(this.instance.id, sessionId, req, timeout ? { timeout: timeout * 1000 } : {});
         return response.data;
     }
     /**
-     * Gets the session command
-     * @param {string} sessionId - Unique identifier for the session
-     * @param {string} commandId - Unique identifier for the command
-     * @returns {Promise<Command>} Session command
+     * Get the logs for a command executed in a session.
+     *
+     * @param {string} sessionId - Unique identifier of the session
+     * @param {string} commandId - Unique identifier of the command
+     * @returns {Promise<string>} Command logs
+     *
+     * @example
+     * const logs = await process.getSessionCommandLogs('my-session', 'cmd-123');
+     * console.log('Command output:', logs);
      */
-    async getSessionCommand(sessionId, commandId) {
-        const response = await this.toolboxApi.getSessionCommand(this.instance.id, sessionId, commandId);
+    async getSessionCommandLogs(sessionId, commandId) {
+        const response = await this.toolboxApi.getSessionCommandLogs(this.instance.id, sessionId, commandId);
         return response.data;
     }
     /**
-     * Lists all sessions in the workspace
-     * @returns {Promise<Session[]>} List of sessions
+     * Lists all active sessions in the Sandbox.
+     *
+     * @returns {Promise<Session[]>} Array of active sessions
+     *
+     * @example
+     * const sessions = await process.listSessions();
+     * sessions.forEach(session => {
+     *   console.log(`Session ${session.sessionId}:`);
+     *   session.commands.forEach(cmd => {
+     *     console.log(`- ${cmd.command} (${cmd.exitCode})`);
+     *   });
+     * });
      */
     async listSessions() {
         const response = await this.toolboxApi.listSessions(this.instance.id);
         return response.data;
     }
     /**
-     * Deletes a session in the workspace
-     * @param {string} sessionId - Unique identifier for the session
+     * Delete a session from the Sandbox.
+     *
+     * @param {string} sessionId - Unique identifier of the session to delete
+     * @returns {Promise<void>}
+     *
+     * @example
+     * // Clean up a completed session
+     * await process.deleteSession('my-session');
      */
     async deleteSession(sessionId) {
         await this.toolboxApi.deleteSession(this.instance.id, sessionId);