computesdk 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -3,6 +3,10 @@
  *
  * Types related to sandbox execution, filesystem, terminal operations
  */
+interface Provider$1 {
+    readonly name: string;
+    readonly sandbox: any;
+}
 /**
  * Supported runtime environments
  */
@@ -57,6 +61,14 @@ interface CreateSandboxOptions {
     timeout?: number;
     /** Custom sandbox ID (if supported by provider) */
     sandboxId?: string;
+    /** Template ID for sandbox creation (provider-specific) */
+    templateId?: string;
+    /** Additional metadata for the sandbox */
+    metadata?: Record<string, any>;
+    /** Domain for sandbox connection (provider-specific) */
+    domain?: string;
+    /** Environment variables for the sandbox */
+    envs?: Record<string, string>;
 }
 /**
  * File system entry information
@@ -91,85 +103,27 @@ interface SandboxFileSystem {
     remove(path: string): Promise<void>;
 }
 /**
- * Terminal session information
- */
-interface TerminalSession {
-    /** Terminal process ID */
-    pid: number;
-    /** Terminal command */
-    command: string;
-    /** Terminal status */
-    status: 'running' | 'exited';
-    /** Exit code (if exited) */
-    exitCode?: number;
-    /** Terminal columns */
-    cols: number;
-    /** Terminal rows */
-    rows: number;
-    /** Write data to this terminal session */
-    write(data: Uint8Array | string): Promise<void>;
-    /** Resize this terminal session */
-    resize(cols: number, rows: number): Promise<void>;
-    /** Kill this terminal session */
-    kill(): Promise<void>;
-    /** Data stream handler */
-    onData?: (data: Uint8Array) => void;
-    /** Exit handler */
-    onExit?: (exitCode: number) => void;
-}
-/**
- * Terminal creation options
- */
-interface TerminalCreateOptions {
-    /** Command to run (defaults to shell) */
-    command?: string;
-    /** Terminal columns */
-    cols?: number;
-    /** Terminal rows */
-    rows?: number;
-    /** Environment variables */
-    env?: Record<string, string>;
-    /** Data stream handler */
-    onData?: (data: Uint8Array) => void;
-    /** Exit handler */
-    onExit?: (exitCode: number) => void;
-}
-/**
- * Terminal operations interface for managing terminal sessions in a sandbox
+ * Error thrown when a command exits with a non-zero status
  */
-interface SandboxTerminal {
-    /** Create a new interactive terminal session */
-    create(options?: TerminalCreateOptions): Promise<TerminalSession>;
-    /** Get existing terminal session by ID */
-    getById(terminalId: string): Promise<TerminalSession | null>;
-    /** List active terminal sessions */
-    list(): Promise<TerminalSession[]>;
-    /** Destroy a terminal session */
-    destroy(terminalId: string): Promise<void>;
+declare class CommandExitError extends Error {
+    result: {
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+        error: boolean;
+    };
+    name: string;
+    constructor(result: {
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+        error: boolean;
+    });
 }
 /**
- * Factory method definitions for sandbox management operations
- * Used by createProvider() to generate ProviderSandboxManager implementations
+ * Type guard to check if an error is a CommandExitError
  */
-interface SandboxManagerMethods<TSandbox = any, TConfig = any> {
-    /** Create a new sandbox */
-    create: (config: TConfig, options?: CreateSandboxOptions) => Promise<{
-        sandbox: TSandbox;
-        sandboxId: string;
-    }>;
-    /** Get an existing sandbox by ID */
-    getById: (config: TConfig, sandboxId: string) => Promise<{
-        sandbox: TSandbox;
-        sandboxId: string;
-    } | null>;
-    /** List all active sandboxes */
-    list: (config: TConfig) => Promise<Array<{
-        sandbox: TSandbox;
-        sandboxId: string;
-    }>>;
-    /** Destroy a sandbox */
-    destroy: (config: TConfig, sandboxId: string) => Promise<void>;
-}
+declare function isCommandExitError(error: unknown): error is CommandExitError;
 /**
  * Base sandbox interface - what developers interact with
  */
@@ -178,20 +132,27 @@ interface Sandbox {
     readonly sandboxId: string;
     /** Provider that created this sandbox */
     readonly provider: string;
+    /** Access to the native provider sandbox instance */
+    readonly instance: unknown;
     /** Execute code in the sandbox */
     runCode(code: string, runtime?: Runtime): Promise<ExecutionResult>;
     /** Execute shell commands */
     runCommand(command: string, args?: string[]): Promise<ExecutionResult>;
     /** Get information about the sandbox */
     getInfo(): Promise<SandboxInfo>;
+    /** Get URL for accessing the sandbox on a specific port */
+    getUrl(options: {
+        port: number;
+        protocol?: string;
+    }): Promise<string>;
+    /** Get the provider instance that created this sandbox */
+    getProvider(): Provider$1;
     /** Kill the sandbox */
     kill(): Promise<void>;
     /** Destroy the sandbox and clean up resources */
     destroy(): Promise<void>;
     /** File system operations */
     readonly filesystem: SandboxFileSystem;
-    /** Terminal operations */
-    readonly terminal: SandboxTerminal;
 }
 
 /**
@@ -227,7 +188,9 @@ interface Provider {
  */
 interface ComputeConfig {
     /** Default provider to use when none is specified */
-    provider: Provider;
+    defaultProvider?: Provider;
+    /** @deprecated Use defaultProvider instead. Kept for backwards compatibility */
+    provider?: Provider;
 }
 /**
  * Parameters for compute.sandbox.create()
@@ -257,7 +220,7 @@ interface ComputeAPI {
     clearConfig(): void;
     sandbox: {
         /** Create a sandbox from a provider (or default provider if configured) */
-        create(params: CreateSandboxParams | CreateSandboxParamsWithOptionalProvider): Promise<Sandbox>;
+        create(params?: CreateSandboxParams | CreateSandboxParamsWithOptionalProvider): Promise<Sandbox>;
         /** Get an existing sandbox by ID from a provider (or default provider if configured) */
         getById(providerOrSandboxId: Provider | string, sandboxId?: string): Promise<Sandbox | null>;
         /** List all active sandboxes from a provider (or default provider if configured) */
@@ -279,50 +242,27 @@ interface ComputeAPI {
 declare const compute: ComputeAPI;
 
 /**
- * Request Handler for Web Framework Integration
+ * Simplified Request Handler for Web Framework Integration
  *
- * Maps web requests to ComputeSDK operations with comprehensive support for:
- * - Sandbox management (create, destroy, getInfo)
- * - Code execution
- * - Filesystem operations
- * - Terminal operations
+ * Handles JSON requests for sandbox and code execution operations.
+ * Terminal support removed - will be re-added with WebSocket VM connections.
  */
 
 /**
- * Extended request structure supporting all SDK capabilities
+ * Request structure supporting sandbox and code execution capabilities
  */
 interface ComputeRequest {
-    /** Type of operation to perform */
-    action: 'compute.sandbox.create' | 'compute.sandbox.destroy' | 'compute.sandbox.getInfo' | 'compute.sandbox.list' | 'compute.sandbox.runCode' | 'compute.sandbox.runCommand' | 'compute.sandbox.filesystem.readFile' | 'compute.sandbox.filesystem.writeFile' | 'compute.sandbox.filesystem.mkdir' | 'compute.sandbox.filesystem.readdir' | 'compute.sandbox.filesystem.exists' | 'compute.sandbox.filesystem.remove' | 'compute.sandbox.terminal.create' | 'compute.sandbox.terminal.getById' | 'compute.sandbox.terminal.list' | 'compute.sandbox.terminal.destroy' | 'compute.sandbox.terminal.write' | 'compute.sandbox.terminal.resize' | 'compute.sandbox.terminal.kill';
-    /** Sandbox ID (required for operations on existing sandboxes) */
+    /** Action in dot notation (e.g., 'compute.sandbox.create') */
+    action: string;
+    /** Parameters for the action */
     sandboxId?: string;
-    /** Code to execute (for runCode action) */
     code?: string;
-    /** Command to run (for runCommand action) */
     command?: string;
-    /** Command arguments (for runCommand action) */
     args?: string[];
-    /** Runtime environment */
     runtime?: Runtime;
-    /** File path (for filesystem operations) */
     path?: string;
-    /** File content (for writeFile action) */
     content?: string;
-    /** Terminal options (for terminal.create) */
-    terminalOptions?: {
-        command?: string;
-        cols?: number;
-        rows?: number;
-        env?: Record<string, string>;
-    };
-    /** Terminal ID (for terminal operations) */
-    terminalId?: string;
-    /** Terminal input data (for terminal.write) */
-    data?: string | Uint8Array;
-    /** Terminal resize dimensions (for terminal.resize) */
-    cols?: number;
-    rows?: number;
-    /** Additional sandbox creation options */
+    /** Sandbox creation options */
     options?: {
         runtime?: Runtime;
         timeout?: number;
@@ -333,140 +273,23 @@ interface ComputeRequest {
  * Response structure for compute operations
  */
 interface ComputeResponse {
-    /** Whether the operation was successful */
     success: boolean;
-    /** Error message if operation failed */
     error?: string;
-    /** Sandbox ID involved in the operation */
     sandboxId: string;
-    /** Provider that handled the operation */
     provider: string;
-    /** Execution result (for runCode/runCommand actions) */
-    result?: {
-        stdout: string;
-        stderr: string;
-        exitCode: number;
-        executionTime: number;
-    };
-    /** Sandbox info (for getInfo action) */
-    info?: {
-        id: string;
-        provider: string;
-        runtime: Runtime;
-        status: string;
-        createdAt: string;
-        timeout: number;
-        metadata?: Record<string, any>;
-    };
-    /** File content (for readFile action) */
-    fileContent?: string;
-    /** Directory listing (for readdir action) */
-    files?: Array<{
-        name: string;
-        path: string;
-        isDirectory: boolean;
-        size: number;
-        lastModified: string;
-    }>;
-    /** File/directory exists (for exists action) */
-    exists?: boolean;
-    /** Sandbox list (for list action) */
-    sandboxes?: Array<{
-        sandboxId: string;
-        provider: string;
-    }>;
-    /** Terminal session (for terminal.create action) */
-    terminal?: {
-        pid: number;
-        command: string;
-        status: string;
-        cols: number;
-        rows: number;
-    };
-    /** Terminal sessions (for terminal.list action) */
-    terminals?: Array<{
-        pid: number;
-        command: string;
-        status: string;
-        cols: number;
-        rows: number;
-    }>;
-    /** WebSocket connection info (for terminal.connect action) */
-    websocket?: {
-        url: string;
-        headers?: Record<string, string>;
-        protocols?: string[];
-    };
+    [key: string]: any;
 }
 /**
- * Parameters for handleComputeRequest
- */
-interface HandleComputeRequestParams {
-    /** The compute request to handle */
-    request: ComputeRequest;
-    /** Provider to use for the operation */
-    provider: Provider;
-}
-/**
- * Handle a compute request - unified API for web frameworks
- *
- * Maps web requests to ComputeSDK operations with full support for:
- * - All sandbox operations via compute.sandbox.*
- * - All filesystem operations via sandbox.filesystem.*
- * - All terminal operations via sandbox.terminal.*
- *
- * @example
- * ```typescript
- * // Execute code
- * const response = await handleComputeRequest({
- *   request: {
- *     action: 'sandbox.runCode',
- *     code: 'print("hello")',
- *     sandboxId: 'existing-sandbox-id' // optional, creates new if not provided
- *   },
- *   provider: e2b({ apiKey: process.env.E2B_API_KEY })
- * });
- *
- * // Filesystem operations
- * const response = await handleComputeRequest({
- *   request: {
- *     action: 'filesystem.writeFile',
- *     sandboxId: 'sandbox-id',
- *     path: '/tmp/hello.py',
- *     content: 'print("Hello from file!")'
- *   },
- *   provider: e2b({ apiKey: process.env.E2B_API_KEY })
- * });
- * ```
+ * Main request handler - handles HTTP requests and pre-parsed bodies
  */
 declare function handleComputeRequest(params: HandleComputeRequestParams): Promise<ComputeResponse>;
-
+declare function handleComputeRequest(requestOrBody: Request | ComputeRequest, provider: Provider): Promise<Response>;
 /**
- * Sandbox Management - Provider-Centric Approach
- *
- * No registry - providers are the single source of truth
- */
-
-/**
- * Sandbox manager - thin wrapper around provider APIs
+ * Legacy export for backward compatibility
  */
-declare class SandboxManager {
-    /**
-     * Create a sandbox from a provider
-     */
-    create(provider: Provider, options?: CreateSandboxOptions): Promise<Sandbox>;
-    /**
-     * Get an existing sandbox by ID from a provider
-     */
-    getById(provider: Provider, sandboxId: string): Promise<Sandbox | null>;
-    /**
-     * List all active sandboxes from a provider
-     */
-    list(provider: Provider): Promise<Sandbox[]>;
-    /**
-     * Destroy a sandbox via a provider
-     */
-    destroy(provider: Provider, sandboxId: string): Promise<void>;
+interface HandleComputeRequestParams {
+    request: ComputeRequest;
+    provider: Provider;
 }
 
 /**
@@ -496,31 +319,17 @@ interface SandboxMethods<TSandbox = any, TConfig = any> {
     runCode: (sandbox: TSandbox, code: string, runtime?: Runtime, config?: TConfig) => Promise<ExecutionResult>;
     runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<ExecutionResult>;
     getInfo: (sandbox: TSandbox) => Promise<SandboxInfo>;
+    getUrl: (sandbox: TSandbox, options: {
+        port: number;
+        protocol?: string;
+    }) => Promise<string>;
     filesystem?: {
-        readFile: (sandbox: TSandbox, path: string) => Promise<string>;
-        writeFile: (sandbox: TSandbox, path: string, content: string) => Promise<void>;
-        mkdir: (sandbox: TSandbox, path: string) => Promise<void>;
-        readdir: (sandbox: TSandbox, path: string) => Promise<FileEntry[]>;
-        exists: (sandbox: TSandbox, path: string) => Promise<boolean>;
-        remove: (sandbox: TSandbox, path: string) => Promise<void>;
-    };
-    terminal?: {
-        create: (sandbox: TSandbox, options?: TerminalCreateOptions) => Promise<{
-            terminal: any;
-            terminalId: string;
-        }>;
-        getById: (sandbox: TSandbox, terminalId: string) => Promise<{
-            terminal: any;
-            terminalId: string;
-        } | null>;
-        list: (sandbox: TSandbox) => Promise<Array<{
-            terminal: any;
-            terminalId: string;
-        }>>;
-        destroy: (sandbox: TSandbox, terminalId: string) => Promise<void>;
-        write: (sandbox: TSandbox, terminal: any, data: Uint8Array | string) => Promise<void>;
-        resize: (sandbox: TSandbox, terminal: any, cols: number, rows: number) => Promise<void>;
-        kill: (sandbox: TSandbox, terminal: any) => Promise<void>;
+        readFile: (sandbox: TSandbox, path: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<ExecutionResult>) => Promise<string>;
+        writeFile: (sandbox: TSandbox, path: string, content: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<ExecutionResult>) => Promise<void>;
+        mkdir: (sandbox: TSandbox, path: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<ExecutionResult>) => Promise<void>;
+        readdir: (sandbox: TSandbox, path: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<ExecutionResult>) => Promise<FileEntry[]>;
+        exists: (sandbox: TSandbox, path: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<ExecutionResult>) => Promise<boolean>;
+        remove: (sandbox: TSandbox, path: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<ExecutionResult>) => Promise<void>;
     };
 }
 /**
@@ -540,4 +349,4 @@ interface ProviderConfig<TSandbox = any, TConfig = any> {
  */
 declare function createProvider<TSandbox, TConfig>(providerConfig: ProviderConfig<TSandbox, TConfig>): (config: TConfig) => Provider;
 
-export { type ComputeAPI, type ComputeConfig, type ComputeRequest, type ComputeResponse, type CreateSandboxOptions, type CreateSandboxParams, type CreateSandboxParamsWithOptionalProvider, type ExecutionResult, type FileEntry, type HandleComputeRequestParams, type Provider, type ProviderConfig, type ProviderSandboxManager, type Runtime, type Sandbox, type SandboxFileSystem, type SandboxInfo, SandboxManager, type SandboxManagerMethods, type SandboxMethods, type SandboxStatus, type SandboxTerminal, type TerminalCreateOptions, type TerminalSession, compute, createProvider, handleComputeRequest };
+export { CommandExitError, type ComputeAPI, type ComputeConfig, type ComputeRequest, type ComputeResponse, type CreateSandboxOptions, type CreateSandboxParams, type CreateSandboxParamsWithOptionalProvider, type ExecutionResult, type FileEntry, type HandleComputeRequestParams, type Provider, type ProviderConfig, type ProviderSandboxManager, type Runtime, type Sandbox, type SandboxFileSystem, type SandboxInfo, type SandboxMethods, type SandboxStatus, compute, createProvider, handleComputeRequest, isCommandExitError };