@daytonaio/sdk 0.19.0-alpha.2 → 0.19.0-alpha.4

package/README.md

@@ -0,0 +1,145 @@
+# Daytona SDK for TypeScript
+
+A TypeScript SDK for interacting with the Daytona API, providing a simple interface for Daytona Sandbox management, Git operations, file system operations, and language server protocol support.
+
+## Installation
+
+You can install the package using npm:
+
+```bash
+npm install @daytonaio/sdk
+```
+
+Or using yarn:
+
+```bash
+yarn add @daytonaio/sdk
+```
+
+## Quick Start
+
+Here's a simple example of using the SDK:
+
+```typescript
+import { Daytona } from '@daytonaio/sdk'
+
+// Initialize using environment variables
+const daytona = new Daytona()
+
+// Create a sandbox
+const sandbox = await daytona.create()
+
+// Run code in the sandbox
+const response = await sandbox.process.codeRun('console.log("Hello World!")')
+console.log(response.result)
+
+// Clean up when done
+await daytona.delete(sandbox)
+```
+
+## Configuration
+
+The SDK can be configured using environment variables or by passing a configuration object:
+
+```typescript
+import { Daytona } from '@daytonaio/sdk'
+
+// Initialize with configuration
+const daytona = new Daytona({
+  apiKey: 'your-api-key',
+  apiUrl: 'your-api-url',
+  target: 'us',
+})
+```
+
+Or using environment variables:
+
+- `DAYTONA_API_KEY`: Your Daytona API key
+- `DAYTONA_API_URL`: The Daytona API URL
+- `DAYTONA_TARGET`: Your target environment
+
+You can also customize sandbox creation:
+
+```typescript
+const sandbox = await daytona.create({
+  language: 'typescript',
+  envVars: { NODE_ENV: 'development' },
+  autoStopInterval: 60, // Auto-stop after 1 hour of inactivity
+})
+```
+
+## Features
+
+- **Sandbox Management**: Create, manage and remove sandboxes
+- **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 sandboxes
+
+## Examples
+
+### Execute Commands
+
+```typescript
+// Execute a shell command
+const response = await sandbox.process.executeCommand('echo "Hello, World!"')
+console.log(response.result)
+
+// Run TypeScript code
+const response = await sandbox.process.codeRun(`
+const x = 10
+const y = 20
+console.log(\`Sum: \${x + y}\`)
+`)
+console.log(response.result)
+```
+
+### File Operations
+
+```typescript
+// Upload a file
+await sandbox.fs.uploadFile(Buffer.from('Hello, World!'), 'path/to/file.txt')
+
+// Download a file
+const content = await sandbox.fs.downloadFile('path/to/file.txt')
+
+// Search for files
+const matches = await sandbox.fs.findFiles(root_dir, 'search_pattern')
+```
+
+### Git Operations
+
+```typescript
+// Clone a repository
+await sandbox.git.clone('https://github.com/example/repo', 'path/to/clone')
+
+// List branches
+const branches = await sandbox.git.branches('path/to/repo')
+
+// Add files
+await sandbox.git.add('path/to/repo', ['file1.txt', 'file2.txt'])
+```
+
+### Language Server Protocol
+
+```typescript
+// Create and start a language server
+const lsp = await sandbox.createLspServer('typescript', 'path/to/project')
+await lsp.start()
+
+// Notify the lsp for the file
+await lsp.didOpen('path/to/file.ts')
+
+// Get document symbols
+const symbols = await lsp.documentSymbols('path/to/file.ts')
+
+// Get completions
+const completions = await lsp.completions('path/to/file.ts', {
+  line: 10,
+  character: 15,
+})
+```
+
+## Contributing
+
+Daytona is Open Source under the [GNU AFFERO GENERAL PUBLIC LICENSE](LICENSE), and is the [copyright of its contributors](NOTICE). If you would like to contribute to the software, read the Developer Certificate of Origin Version 1.1 (https://developercertificate.org/). Afterwards, navigate to the [contributing guide](CONTRIBUTING.md) to get started.

package/dist/Daytona.d.ts

@@ -0,0 +1,393 @@
+import { CreateWorkspaceTargetEnum as SandboxTargetRegion, WorkspaceVolume } from '@daytonaio/api-client';
+import { Image } from './Image';
+import { Sandbox, Sandbox as Workspace } from './Sandbox';
+import { VolumeService } from './Volume';
+/**
+ * Represents a volume mount for a Sandbox.
+ *
+ * @interface
+ * @property {string} volumeId - ID of the Volume to mount
+ * @property {string} mountPath - Path on the Sandbox to mount the Volume
+ */
+export interface VolumeMount extends WorkspaceVolume {
+    volumeId: string;
+    mountPath: string;
+}
+/**
+ * Configuration options for initializing the Daytona client.
+ *
+ * @interface
+ * @property {string} apiKey - API key for authentication with the Daytona API
+ * @property {string} jwtToken - JWT token for authentication with the Daytona API. If not set, it must be provided
+ * via the environment variable `DAYTONA_JWT_TOKEN`, or an API key must be provided instead.
+ * @property {string} organizationId - Organization ID used for JWT-based authentication. Required if a JWT token
+ * is provided, and must be set either here or in the environment variable `DAYTONA_ORGANIZATION_ID`.
+ * @property {string} apiUrl - URL of the Daytona API. Defaults to 'https://app.daytona.io/api'
+ * if not set here and not set in environment variable DAYTONA_API_URL.
+ * @property {CreateSandboxTargetEnum} target - Target location for Sandboxes
+ *
+ * @example
+ * const config: DaytonaConfig = {
+ *     apiKey: "your-api-key",
+ *     apiUrl: "https://your-api.com",
+ *     target: "us"
+ * };
+ * const daytona = new Daytona(config);
+ */
+export interface DaytonaConfig {
+    /** API key for authentication with the Daytona API */
+    apiKey?: string;
+    /** JWT token for authentication with the Daytona API */
+    jwtToken?: string;
+    /** Organization ID for authentication with the Daytona API */
+    organizationId?: string;
+    /** URL of the Daytona API.
+     */
+    apiUrl?: string;
+    /**
+     * @deprecated Use `apiUrl` instead. This property will be removed in future versions.
+     */
+    serverUrl?: string;
+    /** Target environment for sandboxes */
+    target?: SandboxTargetRegion;
+}
+/**
+ * Supported programming languages for code execution
+ */
+export declare enum CodeLanguage {
+    PYTHON = "python",
+    TYPESCRIPT = "typescript",
+    JAVASCRIPT = "javascript"
+}
+/**
+ * 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: SandboxResources = {
+ *     cpu: 2,
+ *     memory: 4,  // 4GB RAM
+ *     disk: 20    // 20GB disk
+ * };
+ */
+export interface SandboxResources {
+    /** CPU allocation for the Sandbox */
+    cpu?: number;
+    /** GPU allocation for the Sandbox */
+    gpu?: number;
+    /** Memory allocation for the Sandbox in GB */
+    memory?: number;
+    /** Disk space allocation for the Sandbox in GB */
+    disk?: number;
+}
+/**
+ * Parameters for creating a new Sandbox.
+ *
+ * @interface
+ * @property {string | Image} [image] - Optional Docker image to use for the Sandbox or an Image instance
+ * @property {string} [user] - Optional os user to use for the Sandbox
+ * @property {CodeLanguage | string} [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 {SandboxResources} [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: CreateSandboxParams = {
+ *     language: 'typescript',
+ *     envVars: { NODE_ENV: 'development' },
+ *     resources: {
+ *         cpu: 2,
+ *         memory: 4 // 4GB RAM
+ *     },
+ *     autoStopInterval: 60  // Auto-stop after 1 hour of inactivity
+ * };
+ * const sandbox = await daytona.create(params, 50);
+ */
+export type CreateSandboxParams = {
+    /** Optional Docker image to use for the Sandbox or an Image instance */
+    image?: string | Image;
+    /** Optional os user to use for the Sandbox */
+    user?: string;
+    /** Programming language for direct code execution */
+    language?: CodeLanguage | string;
+    /** Optional environment variables to set in the sandbox */
+    envVars?: Record<string, string>;
+    /** Sandbox labels */
+    labels?: Record<string, string>;
+    /** Is the Sandbox port preview public */
+    public?: boolean;
+    /** Resource allocation for the Sandbox */
+    resources?: SandboxResources;
+    /** If true, will not wait for the Sandbox to be ready before returning */
+    async?: boolean;
+    /**
+     * 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;
+    /** List of volumes to mount in the Sandbox */
+    volumes?: VolumeMount[];
+};
+/**
+ * Filter for Sandboxes.
+ *
+ * @interface
+ * @property {string} [id] - The ID of the Sandbox to retrieve
+ * @property {Record<string, string>} [labels] - Labels to filter Sandboxes
+ */
+export type SandboxFilter = {
+    id?: string;
+    labels?: Record<string, string>;
+};
+/**
+ * Main class for interacting with the Daytona API.
+ * Provides methods for creating, managing, and interacting with Daytona Sandboxes.
+ * Can be initialized either with explicit configuration or using environment variables.
+ *
+ * @property {VolumeService} volume - Service for managing Daytona Volumes
+ *
+ * @example
+ * // Using environment variables
+ * // Uses DAYTONA_API_KEY, DAYTONA_API_URL, DAYTONA_TARGET
+ * const daytona = new Daytona();
+ * const sandbox = await daytona.create();
+ *
+ * @example
+ * // Using explicit configuration
+ * const config: DaytonaConfig = {
+ *     apiKey: "your-api-key",
+ *     apiUrl: "https://your-api.com",
+ *     target: "us"
+ * };
+ * const daytona = new Daytona(config);
+ *
+ * @class
+ */
+export declare class Daytona {
+    private readonly sandboxApi;
+    private readonly toolboxApi;
+    private readonly imagesApi;
+    private readonly objectStorageApi;
+    private readonly target;
+    private readonly apiKey?;
+    private readonly jwtToken?;
+    private readonly organizationId?;
+    private readonly apiUrl;
+    readonly volume: VolumeService;
+    /**
+     * Creates a new Daytona client instance.
+     *
+     * @param {DaytonaConfig} [config] - Configuration options
+     * @throws {DaytonaError} - `DaytonaError` - When API key is missing
+     */
+    constructor(config?: DaytonaConfig);
+    /**
+     * @deprecated Use `create` with `options` object instead. This method will be removed in a future version.
+     *
+     * Creates Sandboxes with default or custom configurations. You can specify various parameters,
+     * including language, image, resources, environment variables, and volumes for the Sandbox.
+     *
+     * @param {CreateSandboxParams} [params] - Parameters for Sandbox creation
+     * @param {number} [timeout] - Timeout in seconds (0 means no timeout, default is 60)
+     * @returns {Promise<Sandbox>} The created Sandbox instance
+     *
+     * @example
+     * // Create a default sandbox
+     * const sandbox = await daytona.create();
+     *
+     * @example
+     * // Create a custom sandbox
+     * const params: CreateSandboxParams = {
+     *     language: 'typescript',
+     *     image: 'node:18',
+     *     envVars: {
+     *         NODE_ENV: 'development',
+     *         DEBUG: 'true'
+     *     },
+     *     resources: {
+     *         cpu: 2,
+     *         memory: 4 // 4GB RAM
+     *     },
+     *     autoStopInterval: 60
+     * };
+     * const sandbox = await daytona.create(params, 40);
+     */
+    create(params?: CreateSandboxParams, options?: number): Promise<Sandbox>;
+    /**
+     * Creates Sandboxes with default or custom configurations. You can specify various parameters,
+     * including language, image, resources, environment variables, and volumes for the Sandbox.
+     *
+     * @param {CreateSandboxParams} [params] - Parameters for Sandbox creation
+     * @param {object} [options] - Options for the create operation
+     * @param {number} [options.timeout] - Timeout in seconds (0 means no timeout, default is 60)
+     * @param {function} [options.onImageBuildLogs] - Callback function to handle image build logs.
+     * It's invoked only when `params.image` is an instance of `Image` and there's no existing
+     * image in Daytona with the same configuration.
+     * @returns {Promise<Sandbox>} The created Sandbox instance
+     *
+     * @example
+     * const image = Image.debianSlim('3.12').pipInstall('numpy');
+     * const sandbox = await daytona.create({ image }, { timeout: 90, onImageBuildLogs: console.log });
+     *
+     * @example
+     * // Create a custom sandbox
+     * const image = Image.debianSlim('3.12').pipInstall('numpy');
+     * const params: CreateSandboxParams = {
+     *     language: 'typescript',
+     *     image,
+     *     envVars: {
+     *         NODE_ENV: 'development',
+     *         DEBUG: 'true'
+     *     },
+     *     resources: {
+     *         cpu: 2,
+     *         memory: 4 // 4GB RAM
+     *     },
+     *     autoStopInterval: 60
+     * };
+     * const sandbox = await daytona.create(params, { timeout: 100, onImageBuildLogs: console.log });
+     */
+    create(params?: CreateSandboxParams, options?: {
+        onImageBuildLogs?: (chunk: string) => void;
+        timeout?: number;
+    }): Promise<Sandbox>;
+    /**
+     * Gets a Sandbox by its ID.
+     *
+     * @param {string} sandboxId - The ID of the Sandbox to retrieve
+     * @returns {Promise<Sandbox>} The Sandbox
+     *
+     * @example
+     * const sandbox = await daytona.get('my-sandbox-id');
+     * console.log(`Sandbox state: ${sandbox.instance.state}`);
+     */
+    get(sandboxId: string): Promise<Sandbox>;
+    /**
+     * Finds a Sandbox by its ID or labels.
+     *
+     * @param {SandboxFilter} filter - Filter for Sandboxes
+     * @returns {Promise<Sandbox>} First Sandbox that matches the ID or labels.
+     *
+     * @example
+     * const sandbox = await daytona.findOne({ labels: { 'my-label': 'my-value' } });
+     * console.log(`Sandbox: ${await sandbox.info()}`);
+     */
+    findOne(filter: SandboxFilter): Promise<Sandbox>;
+    /**
+     * Lists all Sandboxes filtered by labels.
+     *
+     * @param {Record<string, string>} [labels] - Labels to filter Sandboxes
+     * @returns {Promise<Sandbox[]>} Array of Sandboxes that match the labels.
+     *
+     * @example
+     * const sandboxes = await daytona.list({ 'my-label': 'my-value' });
+     * for (const sandbox of sandboxes) {
+     *     console.log(`${sandbox.id}: ${sandbox.instance.state}`);
+     * }
+     */
+    list(labels?: Record<string, string>): Promise<Sandbox[]>;
+    /**
+     * Starts a Sandbox and waits for it to be ready.
+     *
+     * @param {Sandbox} sandbox - The Sandbox to start
+     * @param {number} [timeout] - Optional timeout in seconds (0 means no timeout)
+     * @returns {Promise<void>}
+     *
+     * @example
+     * const sandbox = await daytona.get('my-sandbox-id');
+     * // Wait up to 60 seconds for the sandbox to start
+     * await daytona.start(sandbox, 60);
+     */
+    start(sandbox: Sandbox, timeout?: number): Promise<void>;
+    /**
+     * Stops a Sandbox.
+     *
+     * @param {Sandbox} sandbox - The Sandbox to stop
+     * @returns {Promise<void>}
+     *
+     * @example
+     * const sandbox = await daytona.get('my-sandbox-id');
+     * await daytona.stop(sandbox);
+     */
+    stop(sandbox: Sandbox): Promise<void>;
+    /**
+     * Deletes a Sandbox.
+     *
+     * @param {Sandbox} sandbox - The Sandbox to delete
+     * @param {number} timeout - Timeout in seconds (0 means no timeout, default is 60)
+     * @returns {Promise<void>}
+     *
+     * @example
+     * const sandbox = await daytona.get('my-sandbox-id');
+     * await daytona.delete(sandbox);
+     */
+    delete(sandbox: Sandbox, timeout?: number): Promise<void>;
+    /** @hidden */
+    remove: (sandbox: Sandbox, timeout?: number) => Promise<void>;
+    /**
+     * Gets the Sandbox by ID.
+     *
+     * @param {string} workspaceId - The ID of the Sandbox to retrieve
+     * @returns {Promise<Workspace>} The Sandbox
+     *
+     * @deprecated Use `getCurrentSandbox` instead. This method will be removed in a future version.
+     */
+    getCurrentWorkspace(workspaceId: string): Promise<Workspace>;
+    /**
+     * Gets the Sandbox by ID.
+     *
+     * @param {string} sandboxId - The ID of the Sandbox to retrieve
+     * @returns {Promise<Sandbox>} The Sandbox
+     *
+     * @example
+     * const sandbox = await daytona.getCurrentSandbox('my-sandbox-id');
+     * console.log(`Current sandbox state: ${sandbox.instance.state}`);
+     */
+    getCurrentSandbox(sandboxId: string): Promise<Sandbox>;
+    /**
+     * Creates and registers a new image from the given Image definition.
+     *
+     * @param {string} name - The name of the image to create.
+     * @param {Image} image - The Image instance.
+     * @param {object} options - Options for the create operation.
+     * @param {boolean} options.verbose - Default is false. Whether to log progress information upon each state change of the image.
+     * @param {number} options.timeout - Default is no timeout. Timeout in seconds (0 means no timeout).
+     * @returns {Promise<void>}
+     *
+     * @example
+     * const image = Image.debianSlim('3.12').pipInstall('numpy');
+     * await daytona.createImage('my-python-image', image);
+     */
+    createImage(name: string, image: Image, options?: {
+        onLogs?: (chunk: string) => void;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Gets the appropriate code toolbox based on language.
+     *
+     * @private
+     * @param {CodeLanguage} [language] - Programming language for the toolbox
+     * @returns {SandboxCodeToolbox} The appropriate code toolbox instance
+     * @throws {DaytonaError} - `DaytonaError` - When an unsupported language is specified
+     */
+    private getCodeToolbox;
+    /**
+     * Processes the image contexts by uploading them to object storage
+     *
+     * @private
+     * @param {Image} image - The Image instance.
+     * @returns {Promise<string[]>} The list of context hashes stored in object storage.
+     */
+    private processImageContext;
+}