alita-sdk 0.3.376__py3-none-any.whl → 0.3.423__py3-none-any.whl

alita_sdk/configurations/bitbucket.py

@@ -1,5 +1,6 @@
 from typing import Optional
 
+from atlassian import Bitbucket
 from pydantic import BaseModel, ConfigDict, Field, SecretStr
 
 
@@ -30,3 +31,97 @@ class BitbucketConfiguration(BaseModel):
     url: str = Field(description="Bitbucket URL")
     username: str = Field(description="Bitbucket Username")
     password: SecretStr = Field(description="Bitbucket Password/App Password")
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Check the connection to Bitbucket.
+        
+        Args:
+            settings: Dictionary containing Bitbucket configuration
+                - url: Bitbucket instance URL (required)
+                - username: Bitbucket username (required)
+                - password: Password or App Password (required)
+        
+        Returns:
+            None if connection successful, error message string if failed
+        """
+        import requests
+        from requests.auth import HTTPBasicAuth
+        
+        # Validate url
+        url = settings.get("url", "").strip()
+        if not url:
+            return "Bitbucket URL is required"
+        
+        # Normalize URL - remove trailing slashes
+        url = url.rstrip("/")
+        
+        # Basic URL validation
+        if not url.startswith(("http://", "https://")):
+            return "Bitbucket URL must start with http:// or https://"
+        
+        # Validate username
+        username = settings.get("username", "").strip()
+        if not username:
+            return "Bitbucket username is required"
+        
+        # Validate password
+        password = settings.get("password")
+        if not password:
+            return "Bitbucket password is required"
+        
+        # Extract password value if it's a SecretStr
+        password_value = password.get_secret_value() if hasattr(password, 'get_secret_value') else password
+        
+        if not password_value or not str(password_value).strip():
+            return "Bitbucket password cannot be empty"
+        
+        # Detect if this is Bitbucket Cloud or Server/Data Center
+        is_cloud = "bitbucket.org" in url.lower() or "api.bitbucket.org" in url.lower()
+        is_correct_bitbucket_domain = "bitbucket" in url.lower()
+        
+        if is_cloud:
+            # Bitbucket Cloud: Use API v2.0
+            # Endpoint: /2.0/user - returns current authenticated user
+            test_url = f"{url}/2.0/user"
+        else:
+            # Bitbucket Server/Data Center: Use API v1.0
+            # Endpoint: /rest/api/1.0/users/{username}
+            test_url = f"{url}/rest/api/1.0/users/{username}"
+        
+        try:
+            response = requests.get(
+                test_url,
+                auth=HTTPBasicAuth(username, str(password_value).strip()),
+                timeout=10
+            )
+            
+            # Check response status
+            if response.status_code == 200:
+                # Successfully connected and authenticated
+                return None
+            elif response.status_code == 401:
+                return "Authentication failed: invalid username or password"
+            elif response.status_code == 403:
+                return "Access forbidden: check user permissions"
+            elif response.status_code == 404:
+                if not is_correct_bitbucket_domain:
+                    return f"Url you provided is incorrect. Please provide correct server or cloud bitbucket url."
+                if is_cloud:
+                    return "Bitbucket API endpoint not found: please provide the correct bitbucket cloud URL"
+                else:
+                    return "Bitbucket API endpoint not found: please provide the correct bitbucket server URL"
+            else:
+                return f"Bitbucket API returned status code {response.status_code}"
+
+        except requests.exceptions.SSLError as e:
+            return f"SSL certificate verification failed: {str(e)}"
+        except requests.exceptions.ConnectionError:
+            return f"Cannot connect to Bitbucket at {url if not is_cloud else 'api.bitbucket.org'}: connection refused"
+        except requests.exceptions.Timeout:
+            return f"Connection to Bitbucket at {url if not is_cloud else 'api.bitbucket.org'} timed out"
+        except requests.exceptions.RequestException as e:
+            return f"Error connecting to Bitbucket: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"

alita_sdk/configurations/confluence.py

@@ -34,4 +34,99 @@ class ConfluenceConfiguration(BaseModel):
     base_url: str = Field(description="Confluence URL")
     username: Optional[str] = Field(description="Confluence Username", default=None)
     api_key: Optional[SecretStr] = Field(description="Confluence API Key", default=None)
-    token: Optional[SecretStr] = Field(description="Confluence Token", default=None)
+    token: Optional[SecretStr] = Field(description="Confluence Token", default=None)
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Check the connection to Confluence.
+        
+        Args:
+            settings: Dictionary containing Confluence configuration
+                - base_url: Confluence instance URL (required)
+                - username: Username for Basic Auth (optional)
+                - api_key: API key/password for Basic Auth (optional)
+                - token: Bearer token for authentication (optional)
+        
+        Returns:
+            None if connection successful, error message string if failed
+        """
+        import requests
+        from requests.auth import HTTPBasicAuth
+        
+        # Validate base_url
+        base_url = settings.get("base_url", "").strip()
+        if not base_url:
+            return "Confluence URL is required"
+        
+        # Normalize URL - remove trailing slashes
+        base_url = base_url.rstrip("/")
+        
+        # Basic URL validation
+        if not base_url.startswith(("http://", "https://")):
+            return "Confluence URL must start with http:// or https://"
+        
+        # Check authentication credentials
+        username = settings.get("username")
+        api_key = settings.get("api_key")
+        token = settings.get("token")
+
+        # Validate authentication - at least one method must be provided
+        has_basic_auth = bool(username and api_key)
+        has_token = bool(token and str(token).strip())
+        
+        # Determine authentication method
+        auth_headers = {}
+        auth = None
+        
+        if has_token:
+            # Bearer token authentication
+            token_value = token.get_secret_value() if hasattr(token, 'get_secret_value') else token
+            auth_headers["Authorization"] = f"Bearer {token_value}"
+        elif has_basic_auth:
+            # Basic authentication
+            api_key_value = api_key.get_secret_value() if hasattr(api_key, 'get_secret_value') else api_key
+            auth = HTTPBasicAuth(username, api_key_value)
+        else:
+            return "Authentication required: provide either token or both username and api_key"
+        
+        # Test connection using /rest/api/user/current endpoint
+        # This endpoint returns current user info and validates authentication
+        test_url = f"{base_url}/rest/api/user/current"
+        
+        try:
+            response = requests.get(
+                test_url,
+                auth=auth,
+                headers=auth_headers,
+                timeout=10
+            )
+            
+            # Check response status
+            if response.status_code == 200:
+                # Successfully connected and authenticated
+                return None
+            elif response.status_code == 401:
+                # Authentication failed
+                if has_token:
+                    return "Authentication failed: Invalid token"
+                else:
+                    return "Authentication failed: Invalid username or API key"
+            elif response.status_code == 403:
+                return """Access forbidden: check permissions and verify the credentials you provided.
+Most probably you provided incorrect credentials (user name and api key or token)"""
+            elif response.status_code == 404:
+                return "Confluence API endpoint not found: verify the Confluence URL"
+            else:
+                return f"Confluence API returned status code {response.status_code}"
+
+        except requests.exceptions.SSLError as e:
+            return f"SSL certificate verification failed: {str(e)}"
+        except requests.exceptions.ConnectionError:
+            return f"Cannot connect to Confluence at {base_url}: connection refused"
+        except requests.exceptions.Timeout:
+            return f"Connection to Confluence at {base_url} timed out"
+        except requests.exceptions.RequestException as e:
+            return f"Error connecting to Confluence: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"

alita_sdk/configurations/gitlab.py

@@ -29,3 +29,82 @@ class GitlabConfiguration(BaseModel):
     )
     url: str = Field(description="GitLab URL")
     private_token: SecretStr = Field(description="GitLab private token")
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Check the connection to GitLab.
+        
+        Args:
+            settings: Dictionary containing GitLab configuration
+                - url: GitLab instance URL (required)
+                - private_token: GitLab private token for authentication (required)
+        
+        Returns:
+            None if connection successful, error message string if failed
+        """
+        import requests
+        
+        # Validate url
+        url = settings.get("url", "").strip()
+        if not url:
+            return "GitLab URL is required"
+        
+        # Normalize URL - remove trailing slashes
+        url = url.rstrip("/")
+        
+        # Basic URL validation
+        if not url.startswith(("http://", "https://")):
+            return "GitLab URL must start with http:// or https://"
+        
+        # Validate private_token
+        private_token = settings.get("private_token")
+        if not private_token:
+            return "GitLab private token is required"
+        
+        # Extract token value if it's a SecretStr
+        token_value = private_token.get_secret_value() if hasattr(private_token, 'get_secret_value') else private_token
+        
+        if not token_value or not str(token_value).strip():
+            return "GitLab private token cannot be empty"
+        
+        # Test connection using /api/v4/user endpoint
+        # This endpoint returns current authenticated user info
+        test_url = f"{url}/api/v4/user"
+        
+        # GitLab supports both PRIVATE-TOKEN header and Authorization Bearer
+        # Using PRIVATE-TOKEN is GitLab-specific and more explicit
+        headers = {
+            "PRIVATE-TOKEN": str(token_value).strip()
+        }
+        
+        try:
+            response = requests.get(
+                test_url,
+                headers=headers,
+                timeout=10
+            )
+            
+            # Check response status
+            if response.status_code == 200:
+                # Successfully connected and authenticated
+                return None
+            elif response.status_code == 401:
+                return "Authentication failed: invalid private token"
+            elif response.status_code == 403:
+                return "Access forbidden: token lacks required permissions"
+            elif response.status_code == 404:
+                return "GitLab API endpoint not found: verify the GitLab URL"
+            else:
+                return f"GitLab API returned status code {response.status_code}"
+
+        except requests.exceptions.SSLError as e:
+            return f"SSL certificate verification failed: {str(e)}"
+        except requests.exceptions.ConnectionError:
+            return f"Cannot connect to GitLab at {url}: connection refused"
+        except requests.exceptions.Timeout:
+            return f"Connection to GitLab at {url} timed out"
+        except requests.exceptions.RequestException as e:
+            return f"Error connecting to GitLab: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"

alita_sdk/configurations/jira.py

@@ -35,3 +35,106 @@ class JiraConfiguration(BaseModel):
     username: Optional[str] = Field(description="Jira Username", default=None)
     api_key: Optional[SecretStr] = Field(description="Jira API Key", default=None)
     token: Optional[SecretStr] = Field(description="Jira Token", default=None)
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Check Jira connection using provided settings.
+        Returns None if connection is successful, error message otherwise.
+        
+        Tests authentication by calling the /rest/api/latest/myself endpoint,
+        which returns information about the currently authenticated user.
+        """
+        import requests
+        from requests.auth import HTTPBasicAuth
+
+        # Extract and validate settings
+        base_url = settings.get('base_url', '').rstrip('/')
+        username = settings.get('username')
+        api_key = settings.get('api_key')
+        token = settings.get('token')
+
+        # Validate base URL
+        if not base_url:
+            return "Base URL is required"
+        
+        if not base_url.startswith(('http://', 'https://')):
+            return "Base URL must start with http:// or https://"
+
+        # Validate authentication - at least one method must be provided
+        has_basic_auth = bool(username and api_key)
+        has_token = bool(token and str(token).strip())
+
+        if not (has_basic_auth or has_token):
+            return "Authentication required: Provide either username + API key, or bearer token"
+
+        # Setup authentication headers
+        headers = {'Accept': 'application/json'}
+        auth = None
+
+        if has_token:
+            # Bearer token authentication
+            token_value = token.get_secret_value() if hasattr(token, 'get_secret_value') else token
+            headers['Authorization'] = f'Bearer {token_value}'
+        elif has_basic_auth:
+            # Basic authentication
+            api_key_value = api_key.get_secret_value() if hasattr(api_key, 'get_secret_value') else api_key
+            auth = HTTPBasicAuth(username, api_key_value)
+
+        # Build API endpoint - using 'latest' for version independence
+        api_endpoint = f"{base_url}/rest/api/latest/myself"
+
+        try:
+            # Make authenticated request to verify credentials
+            response = requests.get(
+                api_endpoint,
+                headers=headers,
+                auth=auth,
+                timeout=10
+            )
+
+            # Handle different response codes
+            if response.status_code == 200:
+                return None  # Success - credentials are valid
+            
+            elif response.status_code == 401:
+                # Authentication failed
+                if has_token:
+                    return "Authentication failed: Invalid bearer token"
+                else:
+                    return "Authentication failed: Invalid username or API key"
+            
+            elif response.status_code == 403:
+                # Authenticated but insufficient permissions
+                return "Access forbidden: Your account has insufficient permissions to access Jira API"
+            
+            elif response.status_code == 404:
+                # API endpoint not found - likely wrong URL
+                return "Jira API endpoint not found: Verify your base URL (e.g., 'https://yourinstance.atlassian.net')"
+            
+            else:
+                # Other HTTP errors - try to extract Jira error messages
+                error_detail = ""
+                try:
+                    error_json = response.json()
+                    if 'errorMessages' in error_json and error_json['errorMessages']:
+                        error_detail = ": " + ", ".join(error_json['errorMessages'])
+                    elif 'message' in error_json:
+                        error_detail = f": {error_json['message']}"
+                except:
+                    pass
+                
+                return f"Connection failed with status {response.status_code}{error_detail}"
+
+        except requests.exceptions.SSLError:
+            return "SSL certificate verification failed: Check your Jira URL or network settings"
+        except requests.exceptions.ConnectionError:
+            return "Connection error: Unable to reach Jira server - check URL and network connectivity"
+        except requests.exceptions.Timeout:
+            return "Connection timeout: Jira server did not respond within 10 seconds"
+        except requests.exceptions.MissingSchema:
+            return "Invalid URL format: URL must include protocol (http:// or https://)"
+        except requests.exceptions.InvalidURL:
+            return "Invalid URL format: Please check your Jira base URL"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"

alita_sdk/configurations/testrail.py

@@ -19,3 +19,91 @@ class TestRailConfiguration(BaseModel):
     url: str = Field(description="Testrail URL")
     email: str = Field(description="TestRail Email")
     password: SecretStr = Field(description="TestRail Password")
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Check the connection to TestRail.
+        
+        Args:
+            settings: Dictionary containing TestRail configuration
+                - url: TestRail instance URL (required)
+                - email: User email for authentication (required)
+                - password: Password or API key for authentication (required)
+        
+        Returns:
+            None if connection successful, error message string if failed
+        """
+        import requests
+        from requests.auth import HTTPBasicAuth
+        
+        # Validate url
+        url = settings.get("url", "").strip()
+        if not url:
+            return "TestRail URL is required"
+        
+        # Normalize URL - remove trailing slashes
+        url = url.rstrip("/")
+        
+        # Basic URL validation
+        if not url.startswith(("http://", "https://")):
+            return "TestRail URL must start with http:// or https://"
+        
+        # Validate email
+        email = settings.get("email", "").strip()
+        if not email:
+            return "TestRail email is required"
+        
+        # Validate password
+        password = settings.get("password")
+        if not password:
+            return "TestRail password is required"
+        
+        # Extract password value if it's a SecretStr
+        password_value = password.get_secret_value() if hasattr(password, 'get_secret_value') else password
+        
+        if not password_value or not password_value.strip():
+            return "TestRail password cannot be empty"
+        
+        # Test connection using /index.php?/api/v2/get_user_by_email endpoint
+        # This endpoint returns user info and validates authentication
+        test_url = f"{url}/index.php?/api/v2/get_user_by_email&email={email}"
+        
+        try:
+            response = requests.get(
+                test_url,
+                auth=HTTPBasicAuth(email, password_value),
+                timeout=10
+            )
+            
+            # Check response status
+            if response.status_code == 200:
+                # Successfully connected and authenticated
+                return None
+            elif response.status_code == 401:
+                return "Authentication failed: invalid email or password"
+            elif response.status_code == 403:
+                return "Access forbidden: check user permissions"
+            elif response.status_code == 404:
+                return "TestRail API endpoint not found: verify the TestRail URL"
+            elif response.status_code == 400:
+                # Could be invalid email format or other bad request
+                try:
+                    error_data = response.json()
+                    error_msg = error_data.get("error", "Bad request")
+                    return f"Bad request: {error_msg}"
+                except:
+                    return "Bad request: check email format and URL"
+            else:
+                return f"TestRail API returned status code {response.status_code}"
+
+        except requests.exceptions.SSLError as e:
+            return f"SSL certificate verification failed: {str(e)}"
+        except requests.exceptions.ConnectionError:
+            return f"Cannot connect to TestRail at {url}: connection refused"
+        except requests.exceptions.Timeout:
+            return f"Connection to TestRail at {url} timed out"
+        except requests.exceptions.RequestException as e:
+            return f"Error connecting to TestRail: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"

alita_sdk/configurations/xray.py

@@ -30,3 +30,96 @@ class XrayConfiguration(BaseModel):
     base_url: str = Field(description="Xray URL")
     client_id: Optional[str] = Field(description="Client ID")
     client_secret: Optional[SecretStr] = Field(description="Client secret")
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Check the connection to Xray Cloud.
+        
+        Args:
+            settings: Dictionary containing Xray configuration
+                - base_url: Xray Cloud URL (required)
+                - client_id: OAuth2 Client ID (required)
+                - client_secret: OAuth2 Client Secret (required)
+        
+        Returns:
+            None if connection successful, error message string if failed
+        """
+        import requests
+        
+        # Validate base_url
+        base_url = settings.get("base_url", "").strip()
+        if not base_url:
+            return "Xray URL is required"
+        
+        # Normalize URL - remove trailing slashes
+        base_url = base_url.rstrip("/")
+        
+        # Basic URL validation
+        if not base_url.startswith(("http://", "https://")):
+            return "Xray URL must start with http:// or https://"
+        
+        # Validate client_id
+        client_id = settings.get("client_id", "").strip() if settings.get("client_id") else ""
+        if not client_id:
+            return "Xray client ID is required"
+        
+        # Validate client_secret
+        client_secret = settings.get("client_secret")
+        if not client_secret:
+            return "Xray client secret is required"
+        
+        # Extract client_secret value if it's a SecretStr
+        client_secret_value = client_secret.get_secret_value() if hasattr(client_secret, 'get_secret_value') else client_secret
+        
+        if not client_secret_value or not str(client_secret_value).strip():
+            return "Xray client secret cannot be empty"
+        
+        # Test connection using /api/v2/authenticate endpoint
+        # This is the OAuth2 token generation endpoint for Xray Cloud
+        auth_url = f"{base_url}/api/v2/authenticate"
+        
+        auth_payload = {
+            "client_id": client_id,
+            "client_secret": str(client_secret_value).strip()
+        }
+        
+        try:
+            response = requests.post(
+                auth_url,
+                json=auth_payload,
+                headers={"Content-Type": "application/json"},
+                timeout=10
+            )
+            
+            # Check response status
+            if response.status_code == 200:
+                # Successfully authenticated and got token
+                return None
+            elif response.status_code == 401:
+                return "Authentication failed: invalid client ID or secret"
+            elif response.status_code == 403:
+                return "Access forbidden: check client credentials"
+            elif response.status_code == 400:
+                # Bad request - could be invalid format
+                try:
+                    error_data = response.json()
+                    error_msg = error_data.get("error", "Bad request")
+                    return f"Bad request: {error_msg}"
+                except:
+                    return "Bad request: check client ID and secret format"
+            elif response.status_code == 404:
+                return "Xray API endpoint not found: verify the Xray URL"
+            else:
+                return f"Xray API returned status code {response.status_code}"
+
+        except requests.exceptions.SSLError as e:
+            return f"SSL certificate verification failed: {str(e)}"
+        except requests.exceptions.ConnectionError:
+            return f"Cannot connect to Xray at {base_url}: connection refused"
+        except requests.exceptions.Timeout:
+            return f"Connection to Xray at {base_url} timed out"
+        except requests.exceptions.RequestException as e:
+            return f"Error connecting to Xray: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"

alita_sdk/configurations/zephyr_enterprise.py

@@ -18,3 +18,96 @@ class ZephyrEnterpriseConfiguration(BaseModel):
     )
     base_url: str = Field(description="Zephyr base URL")
     token: Optional[SecretStr] = Field(description="API token")
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Check the connection to Zephyr Enterprise.
+        
+        Args:
+            settings: Dictionary containing Zephyr Enterprise configuration
+                - base_url: Zephyr Enterprise instance URL (required)
+                - token: API token for authentication (optional, anonymous access possible)
+        
+        Returns:
+            None if connection successful, error message string if failed
+        """
+        import requests
+        
+        # Validate base_url
+        base_url = settings.get("base_url", "").strip()
+        if not base_url:
+            return "Zephyr Enterprise URL is required"
+        
+        # Normalize URL - remove trailing slashes
+        base_url = base_url.rstrip("/")
+        
+        # Basic URL validation
+        if not base_url.startswith(("http://", "https://")):
+            return "Zephyr Enterprise URL must start with http:// or https://"
+        
+        # Get token (optional)
+        token = settings.get("token")
+        
+        # Prepare headers
+        headers = {}
+        has_token = False
+        if token:
+            # Extract token value if it's a SecretStr
+            token_value = token.get_secret_value() if hasattr(token, 'get_secret_value') else token
+            if token_value and str(token_value).strip():
+                headers["Authorization"] = f"Bearer {str(token_value).strip()}"
+                has_token = True
+        
+        # Use different endpoints based on whether authentication is provided
+        # Note: /healthcheck may allow anonymous access, so we use authenticated endpoints when token is provided
+        if has_token:
+            # Test with an endpoint that requires authentication: /flex/services/rest/latest/project
+            # This endpoint lists projects and requires proper authentication
+            test_url = f"{base_url}/flex/services/rest/latest/user/current"
+        else:
+            # Without token, test basic connectivity with healthcheck
+            test_url = f"{base_url}/flex/services/rest/latest/healthcheck"
+        
+        try:
+            response = requests.get(
+                test_url,
+                headers=headers,
+                timeout=10
+            )
+            
+            # Check response status
+            if response.status_code == 200:
+                # Successfully connected
+                return None
+            elif response.status_code == 401:
+                if has_token:
+                    return "Authentication failed: invalid API token"
+                else:
+                    return "Authentication required: provide API token"
+            elif response.status_code == 403:
+                return "Access forbidden: check token permissions"
+            elif response.status_code == 404:
+                # If user endpoint not found, try healthcheck as fallback
+                if has_token:
+                    try:
+                        fallback_url = f"{base_url}/flex/services/rest/latest/healthcheck"
+                        fallback_response = requests.get(fallback_url, headers=headers, timeout=10)
+                        if fallback_response.status_code == 200:
+                            return None
+                    except:
+                        pass
+                return "Zephyr Enterprise API endpoint not found: verify the Zephyr URL"
+            else:
+                return f"Zephyr Enterprise API returned status code {response.status_code}"
+
+        except requests.exceptions.SSLError as e:
+            return f"SSL certificate verification failed: {str(e)}"
+        except requests.exceptions.ConnectionError:
+            return f"Cannot connect to Zephyr Enterprise at {base_url}: connection refused"
+        except requests.exceptions.Timeout:
+            return f"Connection to Zephyr Enterprise at {base_url} timed out"
+        except requests.exceptions.RequestException as e:
+            return f"Error connecting to Zephyr Enterprise: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"