@daytonaio/sdk 0.9.2 → 0.10.0

package/dist/Workspace.d.ts

@@ -1,12 +1,68 @@
+/**
+ * The Daytona SDK core Sandbox functionality.
+ *
+ * Provides the main Workspace class representing a Daytona Sandbox that coordinates file system,
+ * Git, process execution, and LSP functionality. It serves as the central point
+ * for interacting with Daytona Sandboxes.
+ *
+ * The Sandbox must be in a 'started' state before performing operations.
+ *
+ * @module Workspace
+ *
+ * @example
+ * // Create and initialize workspace
+ * const daytona = new Daytona();
+ * const workspace = await daytona.create();
+ *
+ * // File operations
+ * await workspace.fs.uploadFile(
+ *   '/app/config.json',
+ *   new File(['{"setting": "value"}'], 'config.json')
+ * );
+ * const contentBlob = await workspace.fs.downloadFile('/app/config.json');
+ *
+ * // Git operations
+ * await workspace.git.clone('https://github.com/user/repo.git');
+ *
+ * // Process execution
+ * const response = await workspace.process.executeCommand('ls -la');
+ * console.log(response.result);
+ *
+ * // LSP functionality
+ * const lsp = workspace.createLspServer('typescript', '/workspace/project');
+ * await lsp.didOpen('/workspace/project/src/index.ts');
+ * const completions = await lsp.completions('/workspace/project/src/index.ts', {
+ *   line: 10,
+ *   character: 15
+ * });
+ * console.log(completions);
+ *
+ */
 import { ToolboxApi, WorkspaceApi } from '@daytonaio/api-client';
-import { Workspace as WorkspaceInstance } from '@daytonaio/api-client';
+import { WorkspaceState, Workspace as ApiWorkspace, WorkspaceInfo as ApiWorkspaceInfo, CreateWorkspaceTargetEnum as WorkspaceTargetRegion, CreateWorkspaceClassEnum as WorkspaceClass } from '@daytonaio/api-client';
 import { FileSystem } from './FileSystem';
 import { Git } from './Git';
-import { Process } from './Process';
+import { CodeRunParams, Process } from './Process';
 import { LspLanguageId, LspServer } from './LspServer';
+export interface WorkspaceInstance extends Omit<ApiWorkspace, 'info'> {
+    info?: WorkspaceInfo;
+}
 /**
- * Resources allocated to a workspace
+ * Resources allocated to a Sandbox
+ *
  * @interface WorkspaceResources
+ * @property {string} cpu - Number of CPU cores allocated (e.g., "1", "2")
+ * @property {string | null} gpu - Number of GPUs allocated (e.g., "1") or null if no GPU
+ * @property {string} memory - Amount of memory allocated with unit (e.g., "2Gi", "4Gi")
+ * @property {string} disk - Amount of disk space allocated with unit (e.g., "10Gi", "20Gi")
+ *
+ * @example
+ * const resources: WorkspaceResources = {
+ *   cpu: "2",
+ *   gpu: "1",
+ *   memory: "4Gi",
+ *   disk: "20Gi"
+ * };
  */
 export interface WorkspaceResources {
     /** CPU allocation */
@@ -19,10 +75,33 @@ export interface WorkspaceResources {
     disk: string;
 }
 /**
- * Structured information about a workspace
+ * Structured information about a Sandbox
+ *
+ * This interface provides detailed information about a Sandbox's configuration,
+ * resources, and current state.
+ *
  * @interface WorkspaceInfo
+ * @property {string} id - Unique identifier for the Sandbox
+ * @property {string} name - Display name of the Sandbox
+ * @property {string} image - Docker image used for the Sandbox
+ * @property {string} user - OS user running in the Sandbox
+ * @property {Record<string, string>} env - Environment variables set in the Sandbox
+ * @property {Record<string, string>} labels - Custom labels attached to the Sandbox
+ * @property {boolean} public - Whether the Sandbox is publicly accessible
+ * @property {string} target - Target environment where the Sandbox runs
+ * @property {WorkspaceResources} resources - Resource allocations for the Sandbox
+ * @property {string} state - Current state of the Sandbox (e.g., "started", "stopped")
+ * @property {string | null} errorReason - Error message if Sandbox is in error state
+ * @property {string | null} snapshotState - Current state of Sandbox snapshot
+ * @property {Date | null} snapshotStateCreatedAt - When the snapshot state was created
+ *
+ * @example
+ * const workspace = await daytona.create();
+ * const info = await workspace.info();
+ * console.log(`Workspace ${info.name} is ${info.state}`);
+ * console.log(`Resources: ${info.resources.cpu} CPU, ${info.resources.memory} RAM`);
  */
-export interface WorkspaceInfo {
+export interface WorkspaceInfo extends ApiWorkspaceInfo {
     /** Unique identifier */
     id: string;
     /** Workspace name */
@@ -38,17 +117,33 @@ export interface WorkspaceInfo {
     /** Public access flag */
     public: boolean;
     /** Target location */
-    target: string;
+    target: WorkspaceTargetRegion | string;
     /** Resource allocations */
     resources: WorkspaceResources;
     /** Current state */
-    state: string;
+    state: WorkspaceState;
     /** Error reason if any */
     errorReason: string | null;
     /** Snapshot state */
     snapshotState: string | null;
     /** Snapshot state creation timestamp */
     snapshotStateCreatedAt: Date | null;
+    /** Node domain */
+    nodeDomain: string;
+    /** Region */
+    region: WorkspaceTargetRegion;
+    /** Class */
+    class: WorkspaceClass;
+    /** Updated at */
+    updatedAt: string;
+    /** Last snapshot */
+    lastSnapshot: string | null;
+    /** Auto-stop interval in minutes*/
+    autoStopInterval: number;
+    /**
+     * @deprecated Use `state`, `nodeDomain`, `region`, `class`, `updatedAt`, `lastSnapshot`, `resources`, `autoStopInterval` instead.
+     */
+    providerMetadata?: string;
 }
 /**
  * Interface defining methods that a code toolbox must implement
@@ -56,11 +151,23 @@ export interface WorkspaceInfo {
  */
 export interface WorkspaceCodeToolbox {
     /** Generates a command to run the provided code */
-    getRunCommand(code: string): string;
+    getRunCommand(code: string, params?: CodeRunParams): string;
 }
 /**
- * Represents a Daytona workspace instance with file system, git, and process management capabilities
- * @class Workspace
+ * Represents a Daytona Sandbox.
+ *
+ * A Sandbox provides file system operations, Git operations, process execution,
+ * and LSP functionality. It serves as the main interface for interacting with
+ * a Daytona workspace.
+ *
+ * @property {string} id - Unique identifier for the Sandbox
+ * @property {WorkspaceInstance} instance - The underlying Sandbox instance
+ * @property {WorkspaceApi} workspaceApi - API client for Sandbox operations
+ * @property {ToolboxApi} toolboxApi - API client for toolbox operations
+ * @property {WorkspaceCodeToolbox} codeToolbox - Language-specific toolbox implementation
+ * @property {FileSystem} fs - File system operations interface
+ * @property {Git} git - Git operations interface
+ * @property {Process} process - Process execution interface
  */
 export declare class Workspace {
     readonly id: string;
@@ -68,65 +175,174 @@ export declare class Workspace {
     readonly workspaceApi: WorkspaceApi;
     readonly toolboxApi: ToolboxApi;
     private readonly codeToolbox;
-    /** File system operations for the workspace */
+    /** File system operations for the Sandbox */
     readonly fs: FileSystem;
-    /** Git operations for the workspace */
+    /** Git operations for the Sandbox */
     readonly git: Git;
     /** Process and code execution operations */
     readonly process: Process;
     /**
-     * Creates a new workspace instance
-     * @param {string} id - Unique identifier for the workspace
-     * @param {WorkspaceInstance} instance - The underlying workspace instance
-     * @param {WorkspaceApi} workspaceApi - API client for workspace operations
-     * @param {ToolboxApi} toolboxApi - API client for toolbox operations
+     * Creates a new Sandbox instance
      *
+     * @param {string} id - Unique identifier for the Sandbox
+     * @param {WorkspaceInstance} instance - The underlying Sandbox instance
+     * @param {WorkspaceApi} workspaceApi - API client for Sandbox operations
+     * @param {ToolboxApi} toolboxApi - API client for toolbox operations
      * @param {WorkspaceCodeToolbox} codeToolbox - Language-specific toolbox implementation
      */
     constructor(id: string, instance: WorkspaceInstance, workspaceApi: WorkspaceApi, toolboxApi: ToolboxApi, codeToolbox: WorkspaceCodeToolbox);
     /**
-     * Gets the root directory path of the workspace
-     * @returns {Promise<string>} The absolute path to the workspace root
+     * Gets the root directory path of the Sandbox.
+     *
+     * @returns {Promise<string | undefined>} The absolute path to the Sandbox root directory
+     *
+     * @example
+     * const rootDir = await workspace.getWorkspaceRootDir();
+     * console.log(`Workspace root: ${rootDir}`);
      */
     getWorkspaceRootDir(): Promise<string | undefined>;
     /**
-     * Creates a new Language Server Protocol (LSP) server instance
-     * @param {LspLanguageId} languageId - The language server type
-     * @param {string} pathToProject - Path to the project root
-     * @returns {LspServer} A new LSP server instance
+     * Creates a new Language Server Protocol (LSP) server instance.
+     *
+     * The LSP server provides language-specific features like code completion,
+     * diagnostics, and more.
+     *
+     * @param {LspLanguageId} languageId - The language server type (e.g., "typescript")
+     * @param {string} pathToProject - Absolute path to the project root directory
+     * @returns {LspServer} A new LSP server instance configured for the specified language
+     *
+     * @example
+     * const lsp = workspace.createLspServer('typescript', '/workspace/project');
      */
-    createLspServer(languageId: LspLanguageId, pathToProject: string): LspServer;
+    createLspServer(languageId: LspLanguageId | string, pathToProject: string): LspServer;
     /**
-     * Sets labels for the workspace
-     * @param {Record<string, string>} labels - The labels to set
+     * Sets labels for the Sandbox.
+     *
+     * Labels are key-value pairs that can be used to organize and identify Sandboxes.
+     *
+     * @param {Record<string, string>} labels - Dictionary of key-value pairs representing Sandbox labels
+     * @returns {Promise<void>}
+     *
+     * @example
+     * // Set workspace labels
+     * await workspace.setLabels({
+     *   project: 'my-project',
+     *   environment: 'development',
+     *   team: 'backend'
+     * });
      */
     setLabels(labels: Record<string, string>): Promise<void>;
     /**
-     * Starts the workspace
+     * Start the Sandbox.
+     *
+     * This method starts the Sandbox and waits for it to be ready.
+     *
+     * @param {number} [timeout] - Maximum time to wait in seconds. 0 means no timeout.
+     *                            Defaults to 60-second timeout.
      * @returns {Promise<void>}
+     * @throws {DaytonaError} - `DaytonaError` - If Sandbox fails to start or times out
+     *
+     * @example
+     * const workspace = await daytona.getCurrentWorkspace('my-workspace');
+     * await workspace.start(40);  // Wait up to 40 seconds
+     * console.log('Workspace started successfully');
      */
     start(timeout?: number): Promise<void>;
     /**
-     * Stops the workspace
+     * Stops the Sandbox.
+     *
+     * This method stops the Sandbox and waits for it to be fully stopped.
+     *
+     * @param {number} [timeout] - Maximum time to wait in seconds. 0 means no timeout.
+     *                            Defaults to 60-second timeout.
      * @returns {Promise<void>}
+     *
+     * @example
+     * const workspace = await daytona.getCurrentWorkspace('my-workspace');
+     * await workspace.stop();
+     * console.log('Workspace stopped successfully');
      */
-    stop(): Promise<void>;
+    stop(timeout?: number): Promise<void>;
     /**
-     * Deletes the workspace
+     * Deletes the Sandbox.
      * @returns {Promise<void>}
      */
     delete(): Promise<void>;
+    /**
+     * Waits for the Sandbox to reach the 'started' state.
+     *
+     * This method polls the Sandbox status until it reaches the 'started' state
+     * or encounters an error.
+     *
+     * @param {number} [timeout] - Maximum time to wait in seconds. 0 means no timeout.
+     *                               Defaults to 60 seconds.
+     * @returns {Promise<void>}
+     * @throws {DaytonaError} - `DaytonaError` - If the workspace ends up in an error state or fails to start within the timeout period.
+     */
     waitUntilStarted(timeout?: number): Promise<void>;
-    waitUntilStopped(): Promise<void>;
     /**
-     * Get structured information about the workspace
-     * @returns {Promise<WorkspaceInfo>} Structured workspace information
+     * Wait for Sandbox to reach 'stopped' state.
+     *
+     * This method polls the Sandbox status until it reaches the 'stopped' state
+     * or encounters an error.
+     *
+     * @param {number} [timeout] - Maximum time to wait in seconds. 0 means no timeout.
+     *                               Defaults to 60 seconds.
+     * @returns {Promise<void>}
+     * @throws {DaytonaError} - `DaytonaError` - If the workspace fails to stop within the timeout period.
+     */
+    waitUntilStopped(timeout?: number): Promise<void>;
+    /**
+     * Gets structured information about the Sandbox.
+     *
+     * @returns {Promise<WorkspaceInfo>} Detailed information about the Sandbox including its
+     *                                   configuration, resources, and current state
+     *
+     * @example
+     * const info = await workspace.info();
+     * console.log(`Workspace ${info.name}:`);
+     * console.log(`State: ${info.state}`);
+     * console.log(`Resources: ${info.resources.cpu} CPU, ${info.resources.memory} RAM`);
      */
     info(): Promise<WorkspaceInfo>;
     /**
-     * Sets the auto-stop interval for the workspace
-     * @param {number} interval - Number of minutes after which the workspace will automatically stop (must be an integer). Set to 0 to disable auto-stop.
-     * @throws {Error} If interval is negative
+     * Converts an API workspace instance to a WorkspaceInfo object.
+     *
+     * @param {ApiWorkspace} instance - The API workspace instance to convert
+     * @returns {WorkspaceInfo} The converted WorkspaceInfo object
+     */
+    static toWorkspaceInfo(instance: ApiWorkspace): WorkspaceInfo;
+    /**
+     * Set the auto-stop interval for the Sandbox.
+     *
+     * The Sandbox will automatically stop after being idle (no new events) for the specified interval.
+     * Events include any state changes or interactions with the Sandbox through the sdk.
+     * Interactions using Sandbox Previews are not included.
+     *
+     * @param {number} interval - Number of minutes of inactivity before auto-stopping.
+     *                           Set to 0 to disable auto-stop. Default is 15 minutes.
+     * @returns {Promise<void>}
+     * @throws {DaytonaError} - `DaytonaError` - If interval is not a non-negative integer
+     *
+     * @example
+     * // Auto-stop after 1 hour
+     * await workspace.setAutostopInterval(60);
+     * // Or disable auto-stop
+     * await workspace.setAutostopInterval(0);
      */
     setAutostopInterval(interval: number): Promise<void>;
+    /**
+     * Gets the preview link for the workspace at a specific port. If the port is not open, it will open it and return the link.
+     * @param {number} port - The port to open the preview link on
+     * @returns {string} The preview link for the workspace at the specified port
+     * @throws {DaytonaError} If the node domain is not found in the provider metadata
+     */
+    getPreviewLink(port: number): string;
+    /**
+     * Archives the workspace, making it inactive and preserving its state. When sandboxes are archived, the entire filesystem
+     * state is moved to cost-effective object storage, making it possible to keep sandboxes available for an extended period.
+     * The tradeoff between archived and stopped states is that starting an archived sandbox takes more time, depending on its size.
+     * Workspace must be stopped before archiving.
+     */
+    archive(): Promise<void>;
 }