@daytonaio/sdk 0.9.2 → 0.10.1

package/README.md

@@ -2,33 +2,6 @@
 
 A TypeScript SDK for interacting with Daytona Server API, providing a simple interface for Daytona Workspace management, Git operations, file system operations, and language server protocol support.
 
-## Prerequisites
-
-Before using the Daytona SDK, you need to have a running Daytona server instance and proper configuration.
-
-### Server Installation
-
-For detailed instructions on installing and setting up the Daytona server, please refer to the official installation guide at:
-[https://github.com/daytonaio/daytona](https://github.com/daytonaio/daytona)
-
-### Configuration
-
-To use the SDK, you'll need two essential pieces of information:
-
-1. **Server Address**:
-
-   - Run `daytona server config` to get your server's configuration
-   - Look for the `API URL` value in the output
-   - For testing and development, you can use the FRP address provided
-   - For production environments, it's recommended to use a static address
-
-2. **API Key**:
-   - Generate a new API key by running:
-     ```bash
-     daytona api-key generate
-     ```
-   - Save this key securely as it will be needed to authenticate with the server
-
 ## Installation
 
 You can install the package using npm:
@@ -50,41 +23,33 @@ Here's a simple example of using the SDK:
 ```typescript
 import { Daytona } from '@daytonaio/sdk'
 
-// Initialize the Daytona client
+// Initialize using environment variables
 const daytona = new Daytona()
 
-// Create the workspace instance
-const workspace = await daytona.create({
-  language: 'typescript',
-})
+// Create a workspace
+const workspace = await daytona.create()
 
-// Run the code securely inside the workspace
-const response = await workspace.process.code_run('console.log("Hello World!")')
+// Run code in the workspace
+const response = await workspace.process.codeRun('console.log("Hello World!")')
 console.log(response.result)
-```
-
-## Features
 
-- **Workspace Management**: Create, manage and remove workspaces
-- **Git Operations**: Clone repositories, manage branches, and more
-- **File System Operations**: Upload, download, search and manipulate files
-- **Language Server Protocol**: Interact with language servers for code intelligence
-- **Process Management**: Execute code and commands in workspaces
+// Clean up when done
+await daytona.remove(workspace)
+```
 
 ## Configuration
 
 The SDK can be configured using environment variables or by passing a configuration object:
 
 ```typescript
-import { Daytona, DaytonaConfig } from '@daytonaio/sdk'
+import { Daytona } from '@daytonaio/sdk'
 
-const config: DaytonaConfig = {
+// Initialize with configuration
+const daytona = new Daytona({
   apiKey: 'your-api-key',
-  serverUrl: 'https://your-daytona-server',
-  target: 'your-target',
-}
-
-const daytona = new Daytona(config)
+  serverUrl: 'your-server-url',
+  target: 'us',
+})
 ```
 
 Or using environment variables:
@@ -93,26 +58,54 @@ Or using environment variables:
 - `DAYTONA_SERVER_URL`: The Daytona server URL
 - `DAYTONA_TARGET`: Your target environment
 
+You can also customize workspace creation:
+
+```typescript
+const workspace = await daytona.create({
+  language: 'typescript',
+  envVars: { NODE_ENV: 'development' },
+  autoStopInterval: 60, // Auto-stop after 1 hour of inactivity
+})
+```
+
+## Features
+
+- **Workspace Management**: Create, manage and remove workspaces
+- **Git Operations**: Clone repositories, manage branches, and more
+- **File System Operations**: Upload, download, search and manipulate files
+- **Language Server Protocol**: Interact with language servers for code intelligence
+- **Process Management**: Execute code and commands in workspaces
+
 ## Examples
 
-### Execute command
+### Execute Commands
 
 ```typescript
-const response = await workspace.process.code_run(
-  'print("Sum of 3 and 4 is " + str(3 + 4))',
-)
-if (response.code !== 0) {
-  console.log(`Error: ${response.code} ${response.result}`)
-} else {
-  console.log(response.result)
-}
+// Execute a shell command
+const response = await workspace.process.executeCommand('echo "Hello, World!"')
+console.log(response.result)
+
+// Run TypeScript code
+const response = await workspace.process.codeRun(`
+const x = 10
+const y = 20
+console.log(\`Sum: \${x + y}\`)
+`)
+console.log(response.result)
 ```
 
 ### File Operations
 
 ```typescript
 // Upload a file
-await workspace.fs.uploadFile('/path/to/file.txt', new Blob(['Hello, World!']))
+await workspace.fs.uploadFile(
+  '/path/to/file.txt',
+  new File(
+    [Buffer.from('Hello, World!')],
+    'file.txt',
+    { type: 'text/plain' }
+  )
+)
 
 // Download a file
 const content = await workspace.fs.downloadFile('/path/to/file.txt')

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;
 }