@daytonaio/sdk 0.0.0-dev

package/README.md

@@ -0,0 +1,146 @@
+# 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,
+  autoArchiveInterval: 60, // Auto-archive after a Sandbox has been stopped for 1 hour
+})
+```
+
+## 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 [Apache License 2.0](/libs/sdk-typescript//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/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@daytonaio/sdk",
+  "version": "0.0.0-dev",
+  "description": "TypeScript SDK for Daytona",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daytonaio/daytona.git"
+  },
+  "author": "Daytona Platforms Inc.",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/daytonaio/daytona/issues"
+  },
+  "homepage": "https://www.daytona.io/docs",
+  "config": {
+    "docsDir": "../../apps/docs/content/sdk-typescript"
+  },
+  "scripts": {
+    "docs": "bash -O extglob -c 'rm -rf $npm_package_config_docsDir/!(index.mdx)' && typedoc && rm -f $npm_package_config_docsDir/readme.mdx"
+  },
+  "keywords": [],
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.787.0",
+    "@aws-sdk/lib-storage": "^3.798.0",
+    "@iarna/toml": "^2.2.5",
+    "axios": "^1.6.1",
+    "dotenv": "16.5.0",
+    "fast-glob": "^3.3.0",
+    "form-data": "^4.0.0",
+    "shell-quote": "^1.8.2",
+    "tar": "^6.2.0",
+    "untildify": "^5.0.0",
+    "@daytonaio/api-client": "0.0.0-dev"
+  },
+  "packageManager": "yarn@4.6.0",
+  "type": "commonjs"
+}

package/src/Daytona.d.ts

@@ -0,0 +1,331 @@
+import { SandboxVolume } from '@daytonaio/api-client';
+import { Image } from './Image';
+import { Sandbox } from './Sandbox';
+import { SnapshotService } from './Snapshot';
+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 SandboxVolume {
+    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 {string} 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?: string;
+}
+/**
+ * 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 GiB
+ * @property {number} [disk] - Disk space allocation for the Sandbox in GiB
+ *
+ * @example
+ * const resources: SandboxResources = {
+ *     cpu: 2,
+ *     memory: 4,  // 4GiB RAM
+ *     disk: 20    // 20GiB disk
+ * };
+ */
+export interface Resources {
+    /** CPU allocation for the Sandbox */
+    cpu?: number;
+    /** GPU allocation for the Sandbox */
+    gpu?: number;
+    /** Memory allocation for the Sandbox in GiB */
+    memory?: number;
+    /** Disk space allocation for the Sandbox in GiB */
+    disk?: number;
+}
+/**
+ * Base parameters for creating a new Sandbox.
+ *
+ * @interface
+ * @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 {number} [autoStopInterval] - Auto-stop interval in minutes (0 means disabled). Default is 15 minutes.
+ * @property {number} [autoArchiveInterval] - Auto-archive interval in minutes (0 means the maximum interval will be used). Default is 7 days.
+ */
+export type CreateSandboxBaseParams = {
+    user?: string;
+    language?: CodeLanguage | string;
+    envVars?: Record<string, string>;
+    labels?: Record<string, string>;
+    public?: boolean;
+    autoStopInterval?: number;
+    autoArchiveInterval?: number;
+    volumes?: VolumeMount[];
+};
+/**
+ * Parameters for creating a new Sandbox.
+ *
+ * @interface
+ * @property {string | Image} [image] - Custom Docker image to use for the Sandbox. If an Image object is provided,
+ * the image will be dynamically built.
+ * @property {Resources} [resources] - Resource allocation for the Sandbox. If not provided, sandbox will
+ * have default resources.
+ */
+export type CreateSandboxFromImageParams = CreateSandboxBaseParams & {
+    image: string | Image;
+    resources?: Resources;
+};
+/**
+ * Parameters for creating a new Sandbox from a snapshot.
+ *
+ * @interface
+ * @property {string} [snapshot] - Name of the snapshot to use for the Sandbox.
+ */
+export type CreateSandboxFromSnapshotParams = CreateSandboxBaseParams & {
+    snapshot?: string;
+};
+/**
+ * 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
+ * @property {SnapshotService} snapshot - Service for managing Daytona Snapshots
+ *
+ * @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 objectStorageApi;
+    private readonly target?;
+    private readonly apiKey?;
+    private readonly jwtToken?;
+    private readonly organizationId?;
+    private readonly apiUrl;
+    readonly volume: VolumeService;
+    readonly snapshot: SnapshotService;
+    /**
+     * Creates a new Daytona client instance.
+     *
+     * @param {DaytonaConfig} [config] - Configuration options
+     * @throws {DaytonaError} - `DaytonaError` - When API key is missing
+     */
+    constructor(config?: DaytonaConfig);
+    /**
+     * Creates Sandboxes from specified or default snapshot. You can specify various parameters,
+     * including language, image, environment variables, and volumes.
+     *
+     * @param {CreateSandboxFromSnapshotParams} [params] - Parameters for Sandbox creation from snapshot
+     * @param {object} [options] - Options for the create operation
+     * @param {number} [options.timeout] - Timeout in seconds (0 means no timeout, default is 60)
+     * @returns {Promise<Sandbox>} The created Sandbox instance
+     *
+     * @example
+     * const sandbox = await daytona.create();
+     *
+     * @example
+     * // Create a custom sandbox
+     * const params: CreateSandboxFromSnapshotParams = {
+     *     language: 'typescript',
+     *     snapshot: 'my-snapshot-id',
+     *     envVars: {
+     *         NODE_ENV: 'development',
+     *         DEBUG: 'true'
+     *     },
+     *     autoStopInterval: 60
+     * };
+     * const sandbox = await daytona.create(params, { timeout: 100 });
+     */
+    create(params?: CreateSandboxFromSnapshotParams, options?: {
+        timeout?: number;
+    }): Promise<Sandbox>;
+    /**
+     * Creates Sandboxes from specified image available on some registry or declarative Daytona Image. You can specify various parameters,
+     * including resources, language, image, environment variables, and volumes. Daytona creates snapshot from
+     * provided image and uses it to create Sandbox.
+     *
+     * @param {CreateSandboxFromImageParams} [params] - Parameters for Sandbox creation from image
+     * @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.onSnapshotCreateLogs] - Callback function to handle snapshot creation logs.
+     * @returns {Promise<Sandbox>} The created Sandbox instance
+     *
+     * @example
+     * const sandbox = await daytona.create({ image: 'debian:12.9' }, { timeout: 90, onSnapshotCreateLogs: console.log });
+     *
+     * @example
+     * // Create a custom sandbox
+     * const image = Image.base('alpine:3.18').pipInstall('numpy');
+     * const params: CreateSandboxFromImageParams = {
+     *     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, onSnapshotCreateLogs: console.log });
+     */
+    create(params?: CreateSandboxFromImageParams, options?: {
+        onSnapshotCreateLogs?: (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.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 ID: ${sandbox.id}, State: ${sandbox.state}`);
+     */
+    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.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>;
+    /**
+     * 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;
+}