grasp-sdk 0.1.0__py3-none-any.whl

grasp_sdk/__init__.py

@@ -0,0 +1,262 @@
+"""Grasp E2B Python SDK
+
+A Python SDK for E2B platform providing secure command execution 
+and browser automation in isolated cloud environments.
+"""
+
+import asyncio
+import signal
+import sys
+from typing import Dict, Optional, Any, Literal
+
+# Import utilities
+from .utils.logger import init_logger, get_logger
+from .utils.config import get_config
+from .services.browser import BrowserService
+from .services.sandbox import SandboxService
+
+# Import models and types
+from .models import (
+    ISandboxConfig,
+    IBrowserConfig,
+    ICommandOptions,
+    IScriptOptions,
+    SandboxStatus,
+)
+
+__version__ = "0.1.0"
+__author__ = "Grasp Team"
+__email__ = "team@grasp.dev"
+
+
+class GraspServer:
+    """Main Grasp E2B class for browser automation."""
+    
+    def __init__(self, sandbox_config: Optional[Dict[str, Any]] = None):
+        """Initialize GraspServer with configuration.
+        
+        Args:
+            sandbox_config: Optional sandbox configuration overrides
+        """
+        if sandbox_config is None:
+            sandbox_config = {}
+            
+        config = get_config()
+        config['sandbox'].update(sandbox_config)
+        self.config = config
+        
+        # Initialize logger first
+        init_logger(config['logger'])
+        self.logger = get_logger().child('GraspE2B')
+        
+        self.browser_service: Optional[BrowserService] = None
+        
+        self.logger.info(
+            f'GraspE2B initialized (templateId: {config["sandbox"]["templateId"]})'
+        )
+    
+    @property
+    def sandbox(self) -> Optional[SandboxService]:
+        """Get the underlying sandbox service.
+        
+        Returns:
+            SandboxService instance or None
+        """
+        return self.browser_service.get_sandbox() if self.browser_service else None
+    
+    def get_status(self) -> Optional[SandboxStatus]:
+        """Get current sandbox status.
+        
+        Returns:
+            Sandbox status or None
+        """
+        return self.sandbox.get_status() if self.sandbox else None
+    
+    def get_sandbox_id(self) -> Optional[str]:
+        """Get sandbox ID.
+        
+        Returns:
+            Sandbox ID or None
+        """
+        return self.sandbox.get_sandbox_id() if self.sandbox else None
+    
+    async def create_browser_task(
+        self, 
+        browser_type: Literal['chrome-stable', 'chromium'] = 'chromium',
+        config: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Create and launch a browser task.
+        
+        Args:
+            browser_type: Type of browser to launch
+            config: Browser configuration overrides
+            
+        Returns:
+            Dictionary containing browser connection info
+            
+        Raises:
+            RuntimeError: If browser service is already initialized
+        """
+        if self.browser_service:
+            raise RuntimeError('Browser service can only be initialized once')
+        
+        if config is None:
+            config = {}
+            
+        # Create base browser config
+        browser_config: IBrowserConfig = {
+            'cdpPort': 9222,
+            'headless': True,
+            'launchTimeout': 30000,
+            'args': [
+                '--disable-web-security',
+                '--disable-features=VizDisplayCompositor',
+            ],
+            'envs': {},
+        }
+        
+        # Apply user config overrides with type safety
+        if 'cdpPort' in config:
+            browser_config['cdpPort'] = config['cdpPort']
+        if 'headless' in config:
+            browser_config['headless'] = config['headless']
+        if 'launchTimeout' in config:
+            browser_config['launchTimeout'] = config['launchTimeout']
+        if 'args' in config:
+            browser_config['args'] = config['args']
+        if 'envs' in config:
+            browser_config['envs'] = config['envs']
+        
+        self.browser_service = BrowserService(
+            self.config['sandbox'],
+            browser_config
+        )
+        await self.browser_service.initialize()
+        
+        self.logger.info('🌐 Launching Chromium browser with CDP...')
+        cdp_connection = await self.browser_service.launch_browser(browser_type)
+        
+        self.logger.info('✅ Browser launched successfully!')
+        self.logger.debug(
+            f'CDP Connection Info (wsUrl: {cdp_connection.ws_url}, httpUrl: {cdp_connection.http_url})'
+        )
+        
+        return {
+            'id': self.browser_service.id,
+            'ws_url': cdp_connection.ws_url,
+            'http_url': cdp_connection.http_url
+        }
+    
+    async def cleanup(self) -> None:
+        """Cleanup resources.
+        
+        Returns:
+            Promise that resolves when cleanup is complete
+        """
+        self.logger.info('Starting cleanup process')
+        
+        try:
+            # Cleanup browser service
+            if self.browser_service:
+                await self.browser_service.cleanup()
+                
+            self.logger.info('Cleanup completed successfully')
+        except Exception as error:
+            self.logger.error(f'Cleanup failed: {error}')
+            raise
+
+
+# Global server registry
+_servers: Dict[str, GraspServer] = {}
+
+
+async def launch_browser(
+    options: Optional[Dict[str, Any]] = None
+) -> Dict[str, Any]:
+    """Launch a browser instance.
+    
+    Args:
+        options: Launch options including type, headless, adblock settings
+        
+    Returns:
+        Dictionary containing connection information
+    """
+    if options is None:
+        options = {}
+        
+    # Extract browser-specific options
+    browser_type = options.pop('type', 'chromium')
+    headless = options.pop('headless', True)
+    adblock = options.pop('adblock', False)
+    
+    # Create server instance
+    server = GraspServer(options)
+    
+    # Create browser task
+    browser_config = {
+        'headless': headless,
+        'envs': {'ADBLOCK': 'true' if adblock else 'false'}
+    }
+    
+    connection = await server.create_browser_task(browser_type, browser_config)
+    
+    # Register server
+    if connection['id']:
+        _servers[connection['id']] = server
+        
+    return connection
+
+
+async def _graceful_shutdown(signal_name: str) -> None:
+    """Handle graceful shutdown.
+    
+    Args:
+        signal_name: Name of the signal received
+    """
+    print(f'Received {signal_name}, starting cleanup...')
+    
+    # Cleanup all GraspServer instances
+    for server_id in list(_servers.keys()):
+        await _servers[server_id].cleanup()
+        del _servers[server_id]
+    
+    print('All servers cleaned up, exiting...')
+    sys.exit(0)
+
+
+def _setup_signal_handlers() -> None:
+    """Setup signal handlers for graceful shutdown."""
+    def signal_handler(signum, frame):
+        signal_name = signal.Signals(signum).name
+        asyncio.create_task(_graceful_shutdown(signal_name))
+    
+    # Register signal handlers
+    signal.signal(signal.SIGINT, signal_handler)   # Ctrl+C
+    signal.signal(signal.SIGTERM, signal_handler)  # Termination signal
+
+
+# Setup signal handlers on import
+_setup_signal_handlers()
+
+
+# Export all public APIs
+__all__ = [
+    'GraspServer',
+    'launch_browser',
+    'ISandboxConfig',
+    'IBrowserConfig',
+    'ICommandOptions', 
+    'IScriptOptions',
+    'SandboxStatus',
+    'get_config',
+    'init_logger',
+    'get_logger',
+    'BrowserService',
+    'SandboxService',
+]
+
+
+# Default export equivalent
+default = {
+    'launch_browser': launch_browser,
+}

grasp_sdk/models/__init__.py

@@ -0,0 +1,78 @@
+"""Type definitions for Grasp SDK Python implementation.
+
+This module contains TypedDict classes and enums that correspond to 
+the TypeScript interfaces in the Node.js version.
+"""
+
+from typing import TypedDict, Optional, Dict, Any, List, Union
+from typing_extensions import NotRequired
+from enum import Enum
+
+
+class SandboxStatus(Enum):
+    """Sandbox status enumeration."""
+    CREATING = "creating"
+    RUNNING = "running"
+    STOPPED = "stopped"
+    ERROR = "error"
+
+
+class ISandboxConfig(TypedDict):
+    """Sandbox configuration interface."""
+    key: str  # Required: Grasp API key
+    templateId: str  # Required: Sandbox template ID
+    timeout: int  # Required: Default timeout in milliseconds
+    workspace: NotRequired[str]  # Optional: Grasp workspace ID
+    debug: NotRequired[bool]  # Optional: Enable debug mode for detailed logging
+    
+
+class IBrowserConfig(TypedDict):
+    """Browser service configuration interface."""
+    cdpPort: int  # Required: Port for CDP server (default: 9222)
+    args: List[str]  # Required: Chromium launch arguments
+    headless: bool  # Required: Headless mode (default: true)
+    launchTimeout: int  # Required: Timeout for browser launch (default: 30000ms)
+    envs: Dict[str, str]  # Required: The environment variables
+
+
+class ICommandOptions(TypedDict):
+    """Command execution options interface."""
+    inBackground: NotRequired[bool]  # Whether to run command in background
+    timeout: NotRequired[int]  # Timeout in milliseconds
+    cwd: NotRequired[str]  # Working directory
+    nohup: NotRequired[bool]  # Whether to use nohup for command execution
+    
+
+class IScriptOptions(TypedDict):
+    """Script execution options interface."""
+    type: str  # Required: Script type: 'cjs' for CommonJS, 'esm' for ES Modules
+    cwd: NotRequired[str]  # Working directory
+    timeoutMs: NotRequired[int]  # Timeout in milliseconds
+    background: NotRequired[bool]  # Run in background
+    nohup: NotRequired[bool]  # Use nohup for background execution
+    envs: NotRequired[Dict[str, str]]  # The environment variables
+    preCommand: NotRequired[str]  # Pre command
+
+
+class ILoggerConfig(TypedDict):
+    """Logger configuration interface."""
+    level: str  # Required: Log level ('debug' | 'info' | 'warn' | 'error')
+    console: bool  # Required: Enable console output
+    file: NotRequired[str]  # Optional: Log file path
+
+
+class IAppConfig(TypedDict):
+    """Application configuration interface."""
+    sandbox: ISandboxConfig  # Required: E2B configuration
+    logger: ILoggerConfig  # Required: Logger configuration
+
+
+__all__ = [
+    'SandboxStatus',
+    'ISandboxConfig',
+    'IBrowserConfig',
+    'ICommandOptions',
+    'IScriptOptions',
+    'ILoggerConfig',
+    'IAppConfig',
+]