computesdk 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -0,0 +1,467 @@
+/**
+ * ComputeSDK Types
+ *
+ * This file contains all the type definitions for the ComputeSDK.
+ */
+/**
+ * Supported runtime environments
+ */
+type Runtime = 'node' | 'python';
+/**
+ * Supported provider types
+ */
+type ProviderType = 'e2b' | 'vercel' | 'cloudflare' | 'fly' | 'auto';
+/**
+ * Sandbox status types
+ */
+type SandboxStatus = 'running' | 'stopped' | 'error';
+/**
+ * Result of code execution
+ */
+interface ExecutionResult {
+    /** Standard output from the execution */
+    stdout: string;
+    /** Standard error from the execution */
+    stderr: string;
+    /** Exit code from the execution */
+    exitCode: number;
+    /** Time taken for execution in milliseconds */
+    executionTime: number;
+    /** ID of the sandbox where the code was executed */
+    sandboxId: string;
+    /** Provider that executed the code */
+    provider: string;
+}
+/**
+ * Information about a sandbox
+ */
+interface SandboxInfo {
+    /** Unique identifier for the sandbox */
+    id: string;
+    /** Provider hosting the sandbox */
+    provider: string;
+    /** Runtime environment in the sandbox */
+    runtime: Runtime;
+    /** Current status of the sandbox */
+    status: SandboxStatus;
+    /** When the sandbox was created */
+    createdAt: Date;
+    /** Execution timeout in milliseconds */
+    timeout: number;
+    /** Additional provider-specific metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Configuration for container-based providers
+ */
+interface ContainerConfig {
+    /** Docker image to use */
+    image: string;
+    /** Command to run in the container */
+    command?: string[];
+    /** Environment variables for the container */
+    env?: Record<string, string>;
+    /** Ports to expose from the container */
+    ports?: number[];
+    /** Working directory in the container */
+    workdir?: string;
+}
+/**
+ * Configuration for creating a compute sandbox
+ */
+interface SandboxConfig {
+    /** Provider to use for execution */
+    provider?: ProviderType;
+    /** Runtime environment to use */
+    runtime?: Runtime;
+    /** Container configuration if using container-based provider */
+    container?: string | ContainerConfig;
+    /** Execution timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Provider specification that all providers must implement
+ */
+interface ComputeSpecification {
+    /** Version of the specification */
+    specificationVersion: 'v1';
+    /** Provider identifier */
+    provider: string;
+    /** Sandbox identifier */
+    sandboxId: string;
+    /** Execute code in the sandbox */
+    doExecute(code: string, runtime?: Runtime): Promise<ExecutionResult>;
+    /** Kill the sandbox */
+    doKill(): Promise<void>;
+    /** Get information about the sandbox */
+    doGetInfo(): Promise<SandboxInfo>;
+}
+/**
+ * The core compute sandbox interface that all providers expose
+ */
+interface ComputeSandbox {
+    /** Provider identifier */
+    provider: string;
+    /** Sandbox identifier */
+    sandboxId: string;
+    /** Execute code in the sandbox */
+    execute(code: string, runtime?: Runtime): Promise<ExecutionResult>;
+    /** Kill the sandbox */
+    kill(): Promise<void>;
+    /** Get information about the sandbox */
+    getInfo(): Promise<SandboxInfo>;
+}
+/**
+ * Parameters for the executeSandbox function
+ */
+interface ExecuteSandboxParams {
+    /** Sandbox to execute in */
+    sandbox: ComputeSandbox;
+    /** Code to execute */
+    code: string;
+    /** Runtime to use */
+    runtime?: Runtime;
+}
+/**
+ * Provider registry configuration
+ */
+interface ProviderRegistry {
+    /** Get a sandbox by ID */
+    sandbox(id: string): ComputeSandbox;
+}
+/**
+ * Provider factory function type
+ */
+type ProviderFactory = (config?: any) => ComputeSandbox;
+/**
+ * Provider registry map type
+ */
+type ProviderMap = Record<string, ProviderFactory>;
+
+/**
+ * ComputeSDK Error Handling
+ *
+ * This file contains standardized error classes for the ComputeSDK.
+ */
+/**
+ * Base error class for all ComputeSDK errors
+ */
+declare abstract class ComputeError extends Error {
+    /** Error code identifier */
+    abstract readonly code: string;
+    /** Whether the operation can be retried */
+    abstract readonly isRetryable: boolean;
+    /** Provider where the error occurred */
+    readonly provider: string;
+    /** Sandbox ID where the error occurred */
+    readonly sandboxId?: string;
+    /**
+     * Create a new ComputeError
+     *
+     * @param message Error message
+     * @param provider Provider identifier
+     * @param sandboxId Optional sandbox identifier
+     */
+    constructor(message: string, provider: string, sandboxId?: string);
+}
+/**
+ * Error thrown when code execution fails
+ */
+declare class ExecutionError extends ComputeError {
+    /** Error code */
+    readonly code = "EXECUTION_ERROR";
+    /** Execution errors are generally not retryable */
+    readonly isRetryable = false;
+    /** Exit code from the failed execution */
+    readonly exitCode: number;
+    /**
+     * Create a new ExecutionError
+     *
+     * @param message Error message
+     * @param provider Provider identifier
+     * @param exitCode Exit code from the execution
+     * @param sandboxId Optional sandbox identifier
+     */
+    constructor(message: string, provider: string, exitCode: number, sandboxId?: string);
+}
+/**
+ * Error thrown when code execution times out
+ */
+declare class TimeoutError extends ComputeError {
+    /** Error code */
+    readonly code = "TIMEOUT_ERROR";
+    /** Timeout errors may be retryable with a longer timeout */
+    readonly isRetryable = true;
+    /** Timeout duration in milliseconds */
+    readonly timeoutMs: number;
+    /**
+     * Create a new TimeoutError
+     *
+     * @param message Error message
+     * @param provider Provider identifier
+     * @param timeoutMs Timeout duration in milliseconds
+     * @param sandboxId Optional sandbox identifier
+     */
+    constructor(message: string, provider: string, timeoutMs: number, sandboxId?: string);
+}
+/**
+ * Error thrown when provider-specific operations fail
+ */
+declare class ProviderError extends ComputeError {
+    /** Error code */
+    readonly code = "PROVIDER_ERROR";
+    /** Provider errors may be retryable */
+    readonly isRetryable = true;
+    /** Original error from the provider */
+    readonly originalError?: Error;
+    /**
+     * Create a new ProviderError
+     *
+     * @param message Error message
+     * @param provider Provider identifier
+     * @param originalError Optional original error from the provider
+     * @param sandboxId Optional sandbox identifier
+     */
+    constructor(message: string, provider: string, originalError?: Error, sandboxId?: string);
+}
+/**
+ * Error thrown when configuration is invalid
+ */
+declare class ConfigurationError extends ComputeError {
+    /** Error code */
+    readonly code = "CONFIGURATION_ERROR";
+    /** Configuration errors are not retryable without changes */
+    readonly isRetryable = false;
+    /**
+     * Create a new ConfigurationError
+     *
+     * @param message Error message
+     * @param provider Provider identifier
+     * @param sandboxId Optional sandbox identifier
+     */
+    constructor(message: string, provider: string, sandboxId?: string);
+}
+/**
+ * Error thrown when authentication fails
+ */
+declare class AuthenticationError extends ComputeError {
+    /** Error code */
+    readonly code = "AUTHENTICATION_ERROR";
+    /** Authentication errors are not retryable without new credentials */
+    readonly isRetryable = false;
+    /**
+     * Create a new AuthenticationError
+     *
+     * @param message Error message
+     * @param provider Provider identifier
+     * @param sandboxId Optional sandbox identifier
+     */
+    constructor(message: string, provider: string, sandboxId?: string);
+}
+/**
+ * Error thrown when the provider is not available
+ */
+declare class ProviderUnavailableError extends ComputeError {
+    /** Error code */
+    readonly code = "PROVIDER_UNAVAILABLE";
+    /** Provider unavailability may be temporary */
+    readonly isRetryable = true;
+    /**
+     * Create a new ProviderUnavailableError
+     *
+     * @param message Error message
+     * @param provider Provider identifier
+     * @param sandboxId Optional sandbox identifier
+     */
+    constructor(message: string, provider: string, sandboxId?: string);
+}
+
+/**
+ * ComputeSDK Configuration Management
+ *
+ * This file manages configuration and provider selection logic.
+ */
+
+declare global {
+    var DurableObject: any;
+    var WebSocketPair: any;
+}
+declare const DEFAULT_TIMEOUT = 300000;
+/**
+ * Environment variable names for provider API keys
+ */
+declare const ENV_KEYS: {
+    E2B: string;
+    VERCEL: string;
+    CLOUDFLARE: string;
+    FLY: string;
+};
+/**
+ * Detect if running in Cloudflare Workers environment
+ *
+ * @returns True if running in Cloudflare Workers
+ */
+declare function isCloudflareWorkers(): boolean;
+/**
+ * Detect available providers based on environment variables
+ *
+ * @returns Array of available provider types
+ */
+declare function detectAvailableProviders(): ProviderType[];
+/**
+ * Auto-select the best provider based on available API keys
+ *
+ * @returns Selected provider type or undefined if none available
+ */
+declare function autoSelectProvider(): ProviderType | undefined;
+/**
+ * Validate and normalize container configuration
+ *
+ * @param container Container configuration or image string
+ * @returns Normalized container configuration
+ */
+declare function normalizeContainerConfig(container: string | ContainerConfig | undefined): ContainerConfig | undefined;
+/**
+ * Get the appropriate runtime based on provider and configuration
+ *
+ * @param provider Provider type
+ * @param runtime Optional runtime preference
+ * @returns Selected runtime
+ */
+declare function getDefaultRuntime(provider: ProviderType, runtime?: Runtime): Runtime;
+/**
+ * Validate API key for selected provider
+ *
+ * @param provider Provider type
+ * @throws AuthenticationError if API key is missing
+ */
+declare function validateProviderApiKey(provider: ProviderType): void;
+/**
+ * Normalize and validate sandbox configuration
+ *
+ * @param config User-provided configuration
+ * @returns Normalized configuration with defaults applied
+ */
+declare function normalizeSandboxConfig(config?: Partial<SandboxConfig>): SandboxConfig;
+
+/**
+ * Utility functions for ComputeSDK
+ */
+
+/**
+ * Execute code in a sandbox
+ */
+declare function executeSandbox(params: ExecuteSandboxParams): Promise<ExecutionResult>;
+/**
+ * Retry function with exponential backoff
+ */
+declare function retry<T>(fn: () => Promise<T>, maxRetries?: number, baseDelay?: number): Promise<T>;
+
+/**
+ * ComputeSDK Provider Registry
+ *
+ * This file implements the provider registry for managing multiple providers.
+ */
+
+/**
+ * Create a provider registry for managing multiple providers
+ *
+ * @param providers Map of provider factories
+ * @returns Provider registry instance
+ */
+declare function createComputeRegistry(providers: ProviderMap): ProviderRegistry;
+
+/**
+ * ComputeSDK Base Provider
+ *
+ * This file contains the base provider implementation that all
+ * specific provider implementations extend.
+ */
+
+/**
+ * Base implementation of the ComputeSandbox interface
+ *
+ * Provides common functionality and wraps provider-specific implementations.
+ */
+declare abstract class BaseProvider implements ComputeSandbox, ComputeSpecification {
+    /** Specification version */
+    readonly specificationVersion = "v1";
+    /** Provider identifier */
+    readonly provider: string;
+    /** Sandbox identifier */
+    readonly sandboxId: string;
+    /** Execution timeout in milliseconds */
+    protected readonly timeout: number;
+    /**
+     * Create a new base provider
+     *
+     * @param provider Provider identifier
+     * @param timeout Execution timeout in milliseconds
+     */
+    constructor(provider: string, timeout: number);
+    /**
+     * Execute code in the sandbox
+     *
+     * @param code Code to execute
+     * @param runtime Optional runtime to use
+     * @returns Execution result
+     */
+    execute(code: string, runtime?: Runtime): Promise<ExecutionResult>;
+    /**
+     * Kill the sandbox
+     *
+     * @returns Promise that resolves when the sandbox is killed
+     */
+    kill(): Promise<void>;
+    /**
+     * Get information about the sandbox
+     *
+     * @returns Sandbox information
+     */
+    getInfo(): Promise<SandboxInfo>;
+    /**
+     * Provider-specific implementation of code execution
+     *
+     * @param code Code to execute
+     * @param runtime Optional runtime to use
+     * @returns Execution result
+     */
+    abstract doExecute(code: string, runtime?: Runtime): Promise<ExecutionResult>;
+    /**
+     * Provider-specific implementation of sandbox termination
+     *
+     * @returns Promise that resolves when the sandbox is killed
+     */
+    abstract doKill(): Promise<void>;
+    /**
+     * Provider-specific implementation of retrieving sandbox information
+     *
+     * @returns Sandbox information
+     */
+    abstract doGetInfo(): Promise<SandboxInfo>;
+}
+
+declare class ComputeSDK {
+    /**
+     * Create a new sandbox with the specified configuration
+     *
+     * @param config Optional sandbox configuration
+     * @returns Configured sandbox instance
+     */
+    static createSandbox(config?: Partial<SandboxConfig>): ComputeSandbox;
+    /**
+     * Detect available providers based on environment variables
+     *
+     * @returns Array of available provider types
+     */
+    static detectProviders(): ProviderType[];
+}
+
+/**
+ * ComputeSDK Core
+ *
+ * A unified abstraction layer for executing code in secure,
+ * isolated sandboxed environments across multiple cloud providers.
+ */
+
+export { AuthenticationError, BaseProvider, ComputeError, ComputeSDK, type ComputeSandbox, type ComputeSpecification, ConfigurationError, type ContainerConfig, DEFAULT_TIMEOUT, ENV_KEYS, type ExecuteSandboxParams, ExecutionError, type ExecutionResult, ProviderError, type ProviderFactory, type ProviderMap, type ProviderRegistry, type ProviderType, ProviderUnavailableError, type Runtime, type SandboxConfig, type SandboxInfo, type SandboxStatus, TimeoutError, autoSelectProvider, createComputeRegistry, ComputeSDK as default, detectAvailableProviders, executeSandbox, getDefaultRuntime, isCloudflareWorkers, normalizeContainerConfig, normalizeSandboxConfig, retry, validateProviderApiKey };