alita-sdk 0.3.497__py3-none-any.whl → 0.3.515__py3-none-any.whl

alita_sdk/configurations/confluence.py

@@ -1,5 +1,7 @@
 from typing import Optional
+from urllib.parse import urlparse, urlunparse
 
+from atlassian import Confluence
 from pydantic import BaseModel, ConfigDict, Field, SecretStr
 
 
@@ -55,25 +57,53 @@ class ConfluenceConfiguration(BaseModel):
         from requests.auth import HTTPBasicAuth
         
         # Validate base_url
-        base_url = settings.get("base_url", "").strip()
+        base_url_input = settings.get("base_url", "")
+        base_url = base_url_input.strip() if isinstance(base_url_input, str) else ""
         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://"
+
+        # Normalize URL - remove trailing slashes
+        base_url = base_url.rstrip("/")
+
+        # Build candidate base URLs.
+        # Confluence Cloud REST API is typically under /wiki. Users often paste
+        # https://<site>.atlassian.net and shouldn't be forced to know about /wiki.
+        parsed = urlparse(base_url)
+        host = (parsed.hostname or "").lower()
+        path = parsed.path or ""
+
+        def with_wiki_path(url: str) -> str:
+            p = urlparse(url)
+            # Keep existing path if it already starts with /wiki
+            if (p.path or "").startswith("/wiki"):
+                return url
+            # Append /wiki, preserving any existing path (rare but safe)
+            new_path = (p.path or "") + "/wiki"
+            return urlunparse(p._replace(path=new_path.rstrip("/")))
+
+        candidate_base_urls: list[str] = []
+        if host.endswith(".atlassian.net"):
+            # For Atlassian Cloud, prefer the /wiki variant first
+            candidate_base_urls.append(with_wiki_path(base_url))
+        candidate_base_urls.append(base_url)
+        # De-duplicate while preserving order
+        candidate_base_urls = list(dict.fromkeys(candidate_base_urls))
         
         # Check authentication credentials
         username = settings.get("username")
         api_key = settings.get("api_key")
         token = settings.get("token")
 
+        api_key_value = api_key.get_secret_value() if hasattr(api_key, 'get_secret_value') else api_key
+        token_value = token.get_secret_value() if hasattr(token, 'get_secret_value') else 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())
+        has_basic_auth = bool(username and api_key_value and str(api_key_value).strip())
+        has_token = bool(token_value and str(token_value).strip())
         
         # Determine authentication method
         auth_headers = {}
@@ -81,52 +111,56 @@ class ConfluenceConfiguration(BaseModel):
         
         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}"
+            # Test connection using /rest/api/user/current endpoint
+            # This endpoint returns current user info and validates authentication
+            last_status = None
+            for candidate_base in candidate_base_urls:
+                test_url = f"{candidate_base}/rest/api/user/current"
+                response = requests.get(
+                    test_url,
+                    auth=auth,
+                    headers=auth_headers,
+                    timeout=10
+                )
+                last_status = response.status_code
+
+                if response.status_code == 200:
+                    return None
+
+                # If we get 404 on the first candidate, try the next one
+                if response.status_code == 404:
+                    continue
+
+                if response.status_code == 401:
+                    return "Invalid credentials (401) - check token or username/api_key"
+                if response.status_code == 403:
+                    return "Access forbidden (403) - credentials lack Confluence permissions"
+                if response.status_code == 429:
+                    return "Rate limited (429) - please try again later"
+                if 500 <= response.status_code <= 599:
+                    return f"Confluence service error (HTTP {response.status_code})"
+                return f"Confluence request failed (HTTP {response.status_code})"
+
+            # All candidates returned 404
+            return "Confluence API endpoint not found (404) - verify the Confluence URL"
 
         except requests.exceptions.SSLError as e:
-            return f"SSL certificate verification failed: {str(e)}"
+            if 'Hostname mismatch' in str(e):
+                return "SSL error - hostname mismatch. Verify the Confluence URL"
+            return "SSL error - certificate verification failed"
         except requests.exceptions.ConnectionError:
-            return f"Cannot connect to Confluence at {base_url}: connection refused"
+            return "Connection error - unable to reach Confluence. Check URL and network."
         except requests.exceptions.Timeout:
-            return f"Connection to Confluence at {base_url} timed out"
+            return "Connection timeout - Confluence did not respond within 10 seconds. Check URL and network."
         except requests.exceptions.RequestException as e:
-            return f"Error connecting to Confluence: {str(e)}"
-        except Exception as e:
-            return f"Unexpected error: {str(e)}"
+            return f"Request failed: {str(e)}"
+        except Exception:
+            return "Unexpected error during Confluence connection check"

alita_sdk/configurations/figma.py

@@ -1,8 +1,30 @@
+from json import JSONDecodeError
 from typing import Optional
 
+import requests
 from pydantic import BaseModel, ConfigDict, Field, SecretStr
 
 
+def _parse_error_response(response: requests.Response) -> Optional[str]:
+    """
+    Parse error response from Figma API to extract detailed error message.
+
+    Args:
+        response: Response object from requests
+
+    Returns:
+        Detailed error message if found, None otherwise
+    """
+    try:
+        json_response = response.json()
+        error = json_response.get("err") or json_response.get("error")
+        if error and 'Invalid token' in str(error):
+            return "Invalid token. Please verify the Figma token and try again."
+    except (JSONDecodeError, KeyError, AttributeError):
+        pass
+    return None
+
+
 class FigmaConfiguration(BaseModel):
     model_config = ConfigDict(
         json_schema_extra={
@@ -28,3 +50,57 @@ class FigmaConfiguration(BaseModel):
         }
     )
     token: Optional[SecretStr] = Field(description="Figma Token", json_schema_extra={"secret": True}, default=None)
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Test the connection to Figma API.
+
+        Args:
+            settings: Dictionary containing 'token' (required)
+
+        Returns:
+            None if connection is successful, error message string otherwise
+        """
+        token = settings.get("token")
+        if token is None:
+            return "Token is required"
+
+        # Extract secret value if it's a SecretStr
+        if hasattr(token, "get_secret_value"):
+            token = token.get_secret_value()
+
+        # Validate token is not empty
+        if not token or not token.strip():
+            return "Token cannot be empty"
+
+        # Figma API endpoint
+        base_url = "https://api.figma.com"
+        endpoint = f"{base_url}/v1/me"
+
+        try:
+            response = requests.get(
+                endpoint,
+                headers={"X-Figma-Token": token},
+                timeout=10,
+            )
+
+            if response.status_code == 200:
+                return None  # Connection successful
+            elif response.status_code == 401:
+                detailed_error = _parse_error_response(response)
+                return detailed_error if detailed_error else "Invalid token"
+            elif response.status_code == 403:
+                detailed_error = _parse_error_response(response)
+                return detailed_error if detailed_error else "Access forbidden - token may lack required permissions"
+            else:
+                return f"Connection failed with status {response.status_code}"
+
+        except requests.exceptions.Timeout:
+            return "Connection timeout - Figma API is not responding"
+        except requests.exceptions.ConnectionError:
+            return "Connection error - unable to reach Figma API"
+        except requests.exceptions.RequestException as e:
+            return f"Request failed: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"

alita_sdk/configurations/gitlab.py

@@ -99,6 +99,8 @@ class GitlabConfiguration(BaseModel):
                 return f"GitLab API returned status code {response.status_code}"
 
         except requests.exceptions.SSLError as e:
+            if 'Hostname mismatch' in str(e):
+                return "GitLab API endpoint not found: verify the GitLab URL"
             return f"SSL certificate verification failed: {str(e)}"
         except requests.exceptions.ConnectionError:
             return f"Cannot connect to GitLab at {url}: connection refused"

alita_sdk/configurations/qtest.py

@@ -1,3 +1,6 @@
+import re
+
+import requests
 from pydantic import BaseModel, ConfigDict, Field, SecretStr
 
 
@@ -14,6 +17,74 @@ class QtestConfiguration(BaseModel):
             }
         }
     )
-    base_url: str = Field(description="QTest base url")
+    base_url: str = Field(description="QTest base URL")
     qtest_api_token: SecretStr = Field(description="QTest API token")
 
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """Check connectivity and credentials for qTest.
+
+        Strategy:
+        - Validate token against an auth-required endpoint (so an incorrect token is detected).
+
+        Returns:
+            None if successful, otherwise a short actionable error message.
+        """
+        base_url_input = settings.get("base_url")
+        base_url = base_url_input.strip() if isinstance(base_url_input, str) else ""
+        if not base_url:
+            return "QTest base URL is required"
+
+        if not base_url.startswith(("http://", "https://")):
+            return "QTest base URL must start with http:// or https://"
+
+        base_url = base_url.rstrip("/")
+        # If user pasted /api/v3 (or similar), strip it so we can build canonical API URLs.
+        base_url = re.sub(r"/api/v\d+/?$", "", base_url, flags=re.IGNORECASE)
+
+        token = settings.get("qtest_api_token")
+        if token is None:
+            return "QTest API token is required"
+        token_value = token.get_secret_value() if hasattr(token, "get_secret_value") else str(token)
+        if not token_value or not token_value.strip():
+            return "QTest API token cannot be empty"
+
+        headers = {
+            "Authorization": f"Bearer {token_value}",
+            "Content-Type": "application/json",
+        }
+
+        # Auth-required endpoint to validate the token.
+        # /projects works on v3 and requires auth in typical qTest deployments.
+        token_check_url = f"{base_url}/api/v3/projects?pageSize=1&page=1"
+
+        try:
+            resp = requests.get(token_check_url, headers=headers, timeout=10)
+            if resp.status_code == 200:
+                return None
+            elif resp.status_code == 401:
+                return "Invalid or expired QTest API token"
+            elif resp.status_code == 403:
+                return "Access forbidden - token lacks required permissions"
+            elif resp.status_code == 404:
+                return "QTest API not found (404) - verify base URL (do not include /api/v3)"
+            elif resp.status_code == 429:
+                return "Rate limited (429) - please try again later"
+            elif 500 <= resp.status_code <= 599:
+                return f"QTest service error (HTTP {resp.status_code})"
+            else:
+                return f"QTest connection failed (HTTP {resp.status_code})"
+
+        except requests.exceptions.Timeout:
+            return "Connection timeout - qTest did not respond within 10 seconds"
+        except requests.exceptions.ConnectionError:
+            return "Connection error - unable to reach qTest. Check base URL and network."
+        except requests.exceptions.SSLError:
+            return "SSL error - certificate verification failed"
+        except requests.exceptions.RequestException as e:
+            return f"Request failed: {str(e)}"
+        except Exception:
+            return "Unexpected error during qTest connection check"
+
+
+

alita_sdk/configurations/report_portal.py

@@ -1,3 +1,6 @@
+from urllib.parse import quote, urlparse, urlunparse
+
+import requests
 from pydantic import BaseModel, ConfigDict, Field, SecretStr
 
 
@@ -17,3 +20,96 @@ class ReportPortalConfiguration(BaseModel):
     project: str = Field(description="Report Portal Project Name")
     endpoint: str = Field(description="Report Portal Endpoint URL")
     api_key: SecretStr = Field(description="Report Portal API Key")
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """Check the connection to ReportPortal.
+
+        Validates:
+        - endpoint URL format and reachability
+        - API key (token) via an auth-required endpoint
+        - project access (because most ReportPortal APIs are scoped to a project)
+
+        Returns:
+            None if connection successful, error message string otherwise
+        """
+        endpoint_in = settings.get("endpoint")
+        endpoint = endpoint_in.strip() if isinstance(endpoint_in, str) else ""
+        if not endpoint:
+            return "Endpoint is required"
+
+        if not endpoint.startswith(("http://", "https://")):
+            return "Endpoint must start with http:// or https://"
+
+        # Normalize: remove query/fragment and trailing slash.
+        parsed = urlparse(endpoint)
+        endpoint = urlunparse(parsed._replace(query="", fragment="")).rstrip("/")
+
+        # If user pasted an API URL, normalize back to base endpoint.
+        # Common pastes: .../api/v1 or .../api/v1/<project>
+        # lowered = endpoint.lower()
+        # for suffix in ("/api/v1", "/api"):
+        #     if lowered.endswith(suffix):
+        #         endpoint = endpoint[: -len(suffix)].rstrip("/")
+        #         lowered = endpoint.lower()
+        #         break
+
+        project_in = settings.get("project")
+        project = project_in.strip() if isinstance(project_in, str) else ""
+        if not project:
+            return "Project is required"
+
+        api_key = settings.get("api_key")
+        if api_key is None:
+            return "API key is required"
+        api_key_value = api_key.get_secret_value() if hasattr(api_key, "get_secret_value") else str(api_key)
+        if not api_key_value or not api_key_value.strip():
+            return "API key cannot be empty"
+
+        # Auth-required endpoint for verification.
+        # /user endpoint validates the token and project context.
+        project_encoded = quote(project, safe="")
+        test_url = f"{endpoint}/api/v1/project/{project_encoded}"
+
+        try:
+            resp = requests.get(
+                test_url,
+                headers={"Authorization": f"Bearer {api_key_value}"},
+                timeout=10,
+            )
+
+            if resp.status_code == 200:
+                return None
+            if resp.status_code == 401:
+                return "Invalid API key"
+            if resp.status_code == 403:
+                return "Access forbidden - API key has no access to this project"
+            if resp.status_code == 404:
+                return "API endpoint not found (404) - verify endpoint URL and project name"
+            if resp.status_code == 429:
+                return "Rate limited (429) - please try again later"
+            if 500 <= resp.status_code <= 599:
+                return f"ReportPortal service error (HTTP {resp.status_code})"
+            return f"Connection failed (HTTP {resp.status_code})"
+
+        except requests.exceptions.Timeout:
+            return "Connection timeout - ReportPortal did not respond within 10 seconds"
+        except requests.exceptions.SSLError as e:
+            if "Hostname mismatch" in str(e):
+                return "API endpoint not found - verify endpoint URL and project name"
+            return "SSL error - certificate verification failed"
+        except requests.exceptions.ConnectionError:
+            return "Connection error - unable to reach ReportPortal. Check endpoint URL and network."
+        except requests.exceptions.RequestException as e:
+            return f"Request failed: {str(e)}"
+        except Exception:
+            return "Unexpected error during ReportPortal connection check"
+
+if __name__ == '__main__':
+    settings = {
+        "endpoint": "https://reportportal.epam.com",
+        "project": "epm-alta",
+        "api_key": "my-api-key_U1kF0zFvToqcweG3x552cI8pnYkMqszgtht_LHGZhpxwrxDl5nXlmrSf_JLEE8jy",
+    }
+
+    print(ReportPortalConfiguration.check_connection(settings))

alita_sdk/configurations/sharepoint.py

@@ -1,3 +1,5 @@
+import requests
+from office365.onedrive.sharepoint_settings import SharepointSettings
 from pydantic import BaseModel, ConfigDict, Field, SecretStr
 
 
@@ -17,3 +19,149 @@ class SharepointConfiguration(BaseModel):
     client_id: str = Field(description="SharePoint Client ID")
     client_secret: SecretStr = Field(description="SharePoint Client Secret")
     site_url: str = Field(description="SharePoint Site URL")
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Test the connection to SharePoint API using OAuth2 client credentials.
+
+        Args:
+            settings: Dictionary containing 'client_id', 'client_secret', and 'site_url' (all required)
+
+        Returns:
+            None if connection is successful, error message string otherwise
+        """
+        # Validate client_id
+        client_id = settings.get("client_id")
+        if client_id is None or client_id == "":
+            if client_id == "":
+                return "Client ID cannot be empty"
+            return "Client ID is required"
+
+        if not isinstance(client_id, str):
+            return "Client ID must be a string"
+
+        client_id = client_id.strip()
+        if not client_id:
+            return "Client ID cannot be empty"
+
+        # Validate client_secret
+        client_secret = settings.get("client_secret")
+        if client_secret is None:
+            return "Client secret is required"
+
+        # Extract secret value if it's a SecretStr
+        if hasattr(client_secret, "get_secret_value"):
+            client_secret = client_secret.get_secret_value()
+
+        if not client_secret or not client_secret.strip():
+            return "Client secret cannot be empty"
+
+        # Validate site_url
+        site_url = settings.get("site_url")
+        if site_url is None or site_url == "":
+            if site_url == "":
+                return "Site URL cannot be empty"
+            return "Site URL is required"
+
+        if not isinstance(site_url, str):
+            return "Site URL must be a string"
+
+        site_url = site_url.strip()
+        if not site_url:
+            return "Site URL cannot be empty"
+
+        if not site_url.startswith(("http://", "https://")):
+            return "Site URL must start with http:// or https://"
+
+        # Remove trailing slash for consistency
+        site_url = site_url.rstrip("/")
+
+        # Extract tenant and resource from site URL
+        # Expected format: https://<tenant>.sharepoint.com/sites/<site>
+        try:
+            if ".sharepoint.com" not in site_url:
+                return "Site URL must be a valid SharePoint URL (*.sharepoint.com)"
+
+            # Extract tenant (e.g., "contoso" from "contoso.sharepoint.com")
+            parts = site_url.split("//")[1].split(".")
+            if len(parts) < 3:
+                return "Invalid SharePoint URL format"
+            tenant = parts[0]
+
+            # Build token endpoint
+            token_url = f"https://accounts.accesscontrol.windows.net/{tenant}.onmicrosoft.com/tokens/OAuth/2"
+
+            # Build resource (the site URL with /_api appended)
+            resource = f"{site_url.split('/sites/')[0]}@{site_url.split('//')[1].split('/')[0].split('.')[0]}"
+
+        except Exception:
+            return "Failed to parse SharePoint URL - ensure it's in format: https://<tenant>.sharepoint.com/sites/<site>"
+
+        try:
+            # Step 1: Get OAuth2 access token using client credentials
+            token_response = requests.post(
+                token_url,
+                data={
+                    "grant_type": "client_credentials",
+                    "client_id": f"{client_id}@{tenant}.onmicrosoft.com",
+                    "client_secret": client_secret,
+                    "resource": f"00000003-0000-0ff1-ce00-000000000000/{site_url.split('//')[1].split('/')[0]}@{tenant}.onmicrosoft.com"
+                },
+                timeout=10,
+            )
+
+            if token_response.status_code == 400:
+                try:
+                    error_data = token_response.json()
+                    error_desc = error_data.get("error_description", "")
+                    if "not found in the directory" in error_desc.lower():
+                        return "Invalid client ID. Please check if you provide a correct client ID and try again."
+                    elif "client_secret" in error_desc.lower():
+                        return "Invalid client secret"
+                    else:
+                        return f"OAuth2 authentication failed: {error_desc}"
+                except Exception:
+                    return "Invalid client credentials"
+
+            elif token_response.status_code == 401:
+                return "Invalid client secret provided. Please check if you provide a correct client secret and try again."
+            elif token_response.status_code != 200:
+                return f"Failed to obtain access token (status {token_response.status_code})"
+
+            # Extract access token
+            try:
+                token_data = token_response.json()
+                access_token = token_data.get("access_token")
+                if not access_token:
+                    return "No access token received from SharePoint"
+            except Exception:
+                return "Failed to parse token response"
+
+            # Step 2: Test the access token by calling SharePoint API
+            api_url = f"{site_url}/_api/web"
+            api_response = requests.get(
+                api_url,
+                headers={"Authorization": f"Bearer {access_token}"},
+                timeout=10,
+            )
+
+            if api_response.status_code == 200:
+                return None  # Connection successful
+            elif api_response.status_code == 401:
+                return "Access token is invalid or expired"
+            elif api_response.status_code == 403:
+                return "Access forbidden - client may lack required permissions for this site"
+            elif api_response.status_code == 404:
+                return f"Site not found or not accessible: {site_url}"
+            else:
+                return f"SharePoint API request failed with status {api_response.status_code}"
+
+        except requests.exceptions.Timeout:
+            return "Connection timeout - SharePoint is not responding"
+        except requests.exceptions.ConnectionError:
+            return "Connection error - unable to reach SharePoint"
+        except requests.exceptions.RequestException as e:
+            return f"Request failed: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"