@daytonaio/sdk 0.9.2 → 0.10.0

package/dist/Daytona.d.ts

@@ -1,8 +1,67 @@
+/**
+ * Sandboxes are isolated development environments managed by Daytona.
+ * This guide covers how to create, manage, and remove Sandboxes using the SDK.
+ *
+ * @module Daytona
+ *
+ * @example
+ * // Initialize using environment variables (DAYTONA_API_KEY, DAYTONA_SERVER_URL, DAYTONA_TARGET)
+ * const daytona = new Daytona();
+ *
+ * // Create and use a workspace
+ * const workspace = await daytona.create({
+ *     language: 'typescript',
+ *     envVars: { NODE_ENV: 'development' }
+ * });
+ *
+ * // Execute commands in the workspace
+ * const response = await workspace.process.executeCommand('echo "Hello, World!"');
+ * console.log(response.result);
+ *
+ * // Execute code in the workspace
+ * const response = await workspace.process.codeRun('console.log("Hello, World!")');
+ * console.log(response.result);
+ *
+ * @example
+ * // Initialize with explicit configuration
+ * const daytona = new Daytona({
+ *     apiKey: process.env.CUSTOM_API_KEY,
+ *     serverUrl: 'https://daytona.example.com',
+ *     target: 'us'
+ * });
+ *
+ * // Create a custom workspace
+ * const workspace = await daytona.create({
+ *     language: 'typescript',
+ *     image: 'node:18',
+ *     resources: {
+ *         cpu: 2,
+ *         memory: 4 // 4GB RAM
+ *     },
+ *     autoStopInterval: 60 // Auto-stop after 1 hour of inactivity
+ * });
+ *
+ * // Use workspace features
+ * await workspace.git.clone('https://github.com/user/repo.git');
+ * await workspace.process.executeCommand('npm test');
+ */
 import { Workspace } from './Workspace';
-import { CreateWorkspaceTargetEnum } from '@daytonaio/api-client';
+import { CreateWorkspaceTargetEnum as WorkspaceTargetRegion } from '@daytonaio/api-client';
 /**
- * Configuration options for initializing the Daytona client
- * @interface DaytonaConfig
+ * Configuration options for initializing the Daytona client.
+ *
+ * @interface
+ * @property {string} apiKey - API key for authentication with Daytona server
+ * @property {string} serverUrl - URL of the Daytona server
+ * @property {CreateWorkspaceTargetEnum} target - Target location for Sandboxes
+ *
+ * @example
+ * const config: DaytonaConfig = {
+ *     apiKey: "your-api-key",
+ *     serverUrl: "https://your-server.com",
+ *     target: "us"
+ * };
+ * const daytona = new Daytona(config);
  */
 export interface DaytonaConfig {
     /** API key for authentication with Daytona server */
@@ -10,59 +69,123 @@ export interface DaytonaConfig {
     /** URL of the Daytona server */
     serverUrl: string;
     /** Target environment for workspaces */
-    target: CreateWorkspaceTargetEnum;
+    target: WorkspaceTargetRegion;
 }
 /**
  * Supported programming languages for code execution
  */
-export type CodeLanguage = 'python' | 'javascript' | 'typescript';
+export declare enum CodeLanguage {
+    PYTHON = "python",
+    TYPESCRIPT = "typescript",
+    JAVASCRIPT = "javascript"
+}
 /**
- * Resource allocation for a workspace
- * @interface WorkspaceResources
+ * Resource allocation for a Sandbox.
+ *
+ * @interface
+ * @property {number} [cpu] - CPU allocation for the Sandbox in cores
+ * @property {number} [gpu] - GPU allocation for the Sandbox in units
+ * @property {number} [memory] - Memory allocation for the Sandbox in GB
+ * @property {number} [disk] - Disk space allocation for the Sandbox in GB
+ *
+ * @example
+ * const resources: WorkspaceResources = {
+ *     cpu: 2,
+ *     memory: 4,  // 4GB RAM
+ *     disk: 20    // 20GB disk
+ * };
  */
 export interface WorkspaceResources {
-    /** CPU allocation for the workspace */
+    /** CPU allocation for the Sandbox */
     cpu?: number;
-    /** GPU allocation for the workspace */
+    /** GPU allocation for the Sandbox */
     gpu?: number;
-    /** Memory allocation for the workspace in MB */
+    /** Memory allocation for the Sandbox in MB */
     memory?: number;
-    /** Disk space allocation for the workspace in MB */
+    /** Disk space allocation for the Sandbox in MB */
     disk?: number;
 }
 /**
- * Parameters for creating a new workspace
- * @interface CreateWorkspaceParams
+ * Parameters for creating a new Sandbox.
+ *
+ * @interface
+ * @property {string} [id] - Optional Sandbox ID. If not provided, a random ID will be generated
+ * @property {string} [image] - Optional Docker image to use for the Sandbox
+ * @property {string} [user] - Optional os user to use for the Sandbox
+ * @property {CodeLanguage} [language] - Programming language for direct code execution
+ * @property {Record<string, string>} [envVars] - Optional environment variables to set in the Sandbox
+ * @property {Record<string, string>} [labels] - Sandbox labels
+ * @property {boolean} [public] - Is the Sandbox port preview public
+ * @property {string} [target] - Target location for the Sandbox
+ * @property {WorkspaceResources} [resources] - Resource allocation for the Sandbox
+ * @property {boolean} [async] - If true, will not wait for the Sandbox to be ready before returning
+ * @property {number} [timeout] - Timeout in seconds for the Sandbox to be ready (0 means no timeout)
+ * @property {number} [autoStopInterval] - Auto-stop interval in minutes (0 means disabled)
+ *
+ * @example
+ * const params: CreateWorkspaceParams = {
+ *     language: 'typescript',
+ *     envVars: { NODE_ENV: 'development' },
+ *     resources: {
+ *         cpu: 2,
+ *         memory: 4 // 4GB RAM
+ *     },
+ *     autoStopInterval: 60  // Auto-stop after 1 hour of inactivity
+ * };
+ * const workspace = await daytona.create(params, 50);
  */
 export type CreateWorkspaceParams = {
-    /** Optional workspace ID. If not provided, a random ID will be generated */
+    /** Optional Sandbox ID. If not provided, a random ID will be generated */
     id?: string;
-    /** Optional Docker image to use for the workspace */
+    /** Optional Docker image to use for the Sandbox */
     image?: string;
-    /** Optional os user to use for the workspace */
+    /** Optional os user to use for the Sandbox */
     user?: string;
     /** Programming language for direct code execution */
-    language?: CodeLanguage;
+    language?: CodeLanguage | string;
     /** Optional environment variables to set in the workspace */
     envVars?: Record<string, string>;
-    /** Workspace labels */
+    /** Sandbox labels */
     labels?: Record<string, string>;
-    /** Is the workspace port preview public */
+    /** Is the Sandbox port preview public */
     public?: boolean;
-    /** Target location for the workspace */
-    target?: string;
-    /** Resource allocation for the workspace */
+    /** Target location for the Sandbox */
+    target?: WorkspaceTargetRegion | string;
+    /** Resource allocation for the Sandbox */
     resources?: WorkspaceResources;
-    /** If true, will not wait for the workspace to be ready before returning */
+    /** If true, will not wait for the Sandbox to be ready before returning */
     async?: boolean;
-    /** Timeout in seconds, for the workspace to be ready (0 means no timeout) */
+    /**
+     * Timeout in seconds, for the Sandbox to be ready (0 means no timeout)
+     * @deprecated Use methods with `timeout` parameter instead
+     */
     timeout?: number;
     /** Auto-stop interval in minutes (0 means disabled) (must be a non-negative integer) */
     autoStopInterval?: number;
 };
 /**
- * Main class for interacting with Daytona Server API
- * @class Daytona
+ * Main class for interacting with Daytona Server API.
+ *
+ * Provides methods for creating, managing, and interacting with Daytona Sandboxes.
+ * Can be initialized either with explicit configuration or using environment variables.
+ *
+ *
+ * @example
+ * // Using environment variables
+ * // Uses DAYTONA_API_KEY, DAYTONA_SERVER_URL, DAYTONA_TARGET
+ * const daytona = new Daytona();
+ * const workspace = await daytona.create();
+ *
+ * @example
+ * // Using explicit configuration
+ * const config: DaytonaConfig = {
+ *     apiKey: "your-api-key",
+ *     serverUrl: "https://your-server.com",
+ *     target: "us"
+ * };
+ * const daytona = new Daytona(config);
+ *
+ * @class
  */
 export declare class Daytona {
     private readonly workspaceApi;
@@ -71,50 +194,119 @@ export declare class Daytona {
     private readonly apiKey;
     private readonly serverUrl;
     /**
-     * Creates a new Daytona client instance
+     * Creates a new Daytona client instance.
+     *
      * @param {DaytonaConfig} [config] - Configuration options
-     * @throws {Error} When API key or server URL is missing
+     * @throws {DaytonaError} - `DaytonaError` - When API key or server URL is missing
      */
     constructor(config?: DaytonaConfig);
     /**
-     * Creates a new workspace
-     * @param {CreateWorkspaceParams} [params] - Parameters for workspace creation
-     * @returns {Promise<Workspace>} The created workspace instance
+     * Creates Sandboxes with default or custom configurations. You can specify various parameters,
+     * including language, image, resources, environment variables, and volumes for the Sandbox.
+     *
+     * @param {CreateWorkspaceParams} [params] - Parameters for Sandbox creation
+     * @param {number} [timeout] - Timeout in seconds (0 means no timeout, default is 60)
+     * @returns {Promise<Workspace>} The created Sandbox instance
+     *
+     * @example
+     * // Create a default workspace
+     * const workspace = await daytona.create();
+     *
+     * @example
+     * // Create a custom workspace
+     * const params: CreateWorkspaceParams = {
+     *     language: 'typescript',
+     *     image: 'node:18',
+     *     envVars: {
+     *         NODE_ENV: 'development',
+     *         DEBUG: 'true'
+     *     },
+     *     resources: {
+     *         cpu: 2,
+     *         memory: 4 // 4GB RAM
+     *     },
+     *     autoStopInterval: 60
+     * };
+     * const workspace = await daytona.create(params, 40);
      */
-    create(params?: CreateWorkspaceParams): Promise<Workspace>;
+    create(params: CreateWorkspaceParams, timeout?: number): Promise<Workspace>;
     /**
-     * Gets a workspace by its ID
-     * @param {string} workspaceId - The ID of the workspace to retrieve
-     * @returns {Promise<Workspace>} The workspace instance
+     * Gets a Sandbox by its ID.
+     *
+     * @param {string} workspaceId - The ID of the Sandbox to retrieve
+     * @returns {Promise<Workspace>} The Sandbox
+     *
+     * @example
+     * const workspace = await daytona.get('my-workspace-id');
+     * console.log(`Workspace state: ${workspace.instance.state}`);
      */
     get(workspaceId: string): Promise<Workspace>;
     /**
-     * Lists all workspaces
-     * @returns {Promise<Workspace[]>} The list of workspaces
+     * Lists all Sandboxes.
+     *
+     * @returns {Promise<Workspace[]>} Array of Sandboxes
+     *
+     * @example
+     * const workspaces = await daytona.list();
+     * for (const workspace of workspaces) {
+     *     console.log(`${workspace.id}: ${workspace.instance.state}`);
+     * }
      */
     list(): Promise<Workspace[]>;
     /**
-     * Starts a workspace
-     * @param {Workspace} workspace - The workspace to start
+     * Starts a Sandbox and waits for it to be ready.
+     *
+     * @param {Workspace} workspace - The Sandbox to start
+     * @param {number} [timeout] - Optional timeout in seconds (0 means no timeout)
+     * @returns {Promise<void>}
+     *
+     * @example
+     * const workspace = await daytona.get('my-workspace-id');
+     * // Wait up to 60 seconds for the workspace to start
+     * await daytona.start(workspace, 60);
      */
     start(workspace: Workspace, timeout?: number): Promise<void>;
     /**
-     * Stops a workspace
-     * @param {Workspace} workspace - The workspace to stop
+     * Stops a Sandbox.
+     *
+     * @param {Workspace} workspace - The Sandbox to stop
      * @returns {Promise<void>}
+     *
+     * @example
+     * const workspace = await daytona.get('my-workspace-id');
+     * await daytona.stop(workspace);
      */
     stop(workspace: Workspace): Promise<void>;
     /**
-     * Removes a workspace
-     * @param {Workspace} workspace - The workspace to remove
+     * Removes a Sandbox.
+     *
+     * @param {Workspace} workspace - The Sandbox to remove
+     * @param {number} timeout - Timeout in seconds (0 means no timeout, default is 60)
      * @returns {Promise<void>}
+     *
+     * @example
+     * const workspace = await daytona.get('my-workspace-id');
+     * await daytona.remove(workspace);
      */
-    remove(workspace: Workspace): Promise<void>;
+    remove(workspace: Workspace, timeout?: number): Promise<void>;
     /**
-     * Gets the current workspace by ID
-     * @param {string} workspaceId - The ID of the workspace to retrieve
-     * @returns {Promise<Workspace>} The workspace instance
+     * Gets the Sandbox by ID.
+     *
+     * @param {string} workspaceId - The ID of the Sandbox to retrieve
+     * @returns {Promise<Workspace>} The Sandbox
+     *
+     * @example
+     * const workspace = await daytona.getCurrentWorkspace('my-workspace-id');
+     * console.log(`Current workspace state: ${workspace.instance.state}`);
      */
     getCurrentWorkspace(workspaceId: string): Promise<Workspace>;
+    /**
+     * Gets the appropriate code toolbox based on language.
+     *
+     * @private
+     * @param {CodeLanguage} [language] - Programming language for the toolbox
+     * @returns {WorkspaceCodeToolbox} The appropriate code toolbox instance
+     * @throws {DaytonaError} - `DaytonaError` - When an unsupported language is specified
+     */
     private getCodeToolbox;
 }