alita-sdk 0.3.462__py3-none-any.whl → 0.3.627__py3-none-any.whl

alita_sdk/configurations/openapi.py

@@ -0,0 +1,329 @@
+from typing import Any, Literal, Optional
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, model_validator
+
+import base64
+import requests
+
+
+class OpenApiConfiguration(BaseModel):
+    """
+    OpenAPI configuration for authentication.
+    
+    Supports three authentication modes:
+    - Anonymous: No authentication (all fields empty)
+    - API Key: Static key sent via header (Bearer, Basic, or Custom)
+    - OAuth2 Client Credentials: Machine-to-machine authentication flow
+    
+    Note: Only OAuth2 Client Credentials flow is supported. Authorization Code flow
+    is not supported as it requires user interaction and pre-registered redirect URLs.
+    """
+    
+    model_config = ConfigDict(
+        extra='allow',
+        json_schema_extra={
+            "metadata": {
+                "label": "OpenAPI",
+                "icon_url": "openapi.svg",
+                "categories": ["integrations"],
+                "type": "openapi",
+                "extra_categories": ["api", "openapi", "swagger"],
+                "check_connection": {
+                    "enabled_when": {
+                        "all_fields_set": ["client_id", "client_secret", "method", "token_url"],
+                    },
+                    "disabled_tooltip": "Available only for OAuth (Client Credentials). Please setup client_id, client_secret, method and token_url to activate it on setup.",
+                },
+                "sections": {
+                    "auth": {
+                        "required": False,
+                        "subsections": [
+                            {
+                                "name": "API Key",
+                                "fields": ["api_key", "auth_type", "custom_header_name"],
+                            },
+                            {
+                                "name": "OAuth",
+                                "fields": [
+                                    "client_id",
+                                    "client_secret",
+                                    "token_url",
+                                    "scope",
+                                    "method",
+                                ],
+                            },
+                        ],
+                    },
+                },
+                "section": "credentials",
+            }
+        }
+    )
+
+    # =========================================================================
+    # API Key Authentication Fields
+    # =========================================================================
+    
+    api_key: Optional[SecretStr] = Field(
+        default=None,
+        description=(
+            "API key value (stored as a secret). Used when selecting 'API Key' authentication subsection."
+        ),
+    )
+    auth_type: Optional[Literal['Basic', 'Bearer', 'Custom']] = Field(
+        default=None,
+        description=(
+            "How to apply the API key. "
+            "- 'Bearer': sets 'Authorization: Bearer <api_key>' "
+            "- 'Basic': sets 'Authorization: Basic <api_key>' "
+            "- 'custom': sets '<custom_header_name>: <api_key>'"
+        ),
+    )
+    custom_header_name: Optional[str] = Field(
+        default=None,
+        description="Custom header name to use when auth_type='custom' (e.g. 'X-Api-Key').",
+        json_schema_extra={'visible_when': {'field': 'auth_type', 'value': 'custom'}},
+    )
+
+    # =========================================================================
+    # OAuth2 Client Credentials Flow Fields
+    # =========================================================================
+    
+    client_id: Optional[str] = Field(
+        default=None, 
+        description='OAuth2 client ID (also known as Application ID or App ID)'
+    )
+    client_secret: Optional[SecretStr] = Field(
+        default=None, 
+        description='OAuth2 client secret (stored securely)'
+    )
+    token_url: Optional[str] = Field(
+        default=None, 
+        description=(
+            'OAuth2 token endpoint URL for obtaining access tokens. '
+            'Examples: '
+            'Azure AD: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token, '
+            'Google: https://oauth2.googleapis.com/token, '
+            'Auth0: https://{domain}/oauth/token, '
+            'Spotify: https://accounts.spotify.com/api/token'
+        )
+    )
+    scope: Optional[str] = Field(
+        default=None, 
+        description=(
+            'OAuth2 scope(s), space-separated if multiple (per OAuth2 RFC 6749). '
+            'Examples: "user-read-private user-read-email" (Spotify), '
+            '"api://app-id/.default" (Azure), '
+            '"https://www.googleapis.com/auth/cloud-platform" (Google)'
+        )
+    )
+    method: Optional[Literal['default', 'Basic']] = Field(
+        default=None,
+        description=(
+            "Token exchange method for client credentials flow. "
+            "'default': Sends client_id and client_secret in POST body (Azure AD, Auth0, most providers). "
+            "'Basic': Sends credentials via HTTP Basic auth header - required by Spotify, some AWS services, and certain OAuth providers."
+        ),
+    )
+
+    @model_validator(mode='before')
+    @classmethod
+    def _validate_auth_consistency(cls, values):
+        if not isinstance(values, dict):
+            return values
+
+        # OAuth: if any OAuth field is provided, require the essential ones
+        has_any_oauth = any(
+            (values.get('client_id'), values.get('client_secret'), values.get('token_url'))
+        )
+        if has_any_oauth:
+            missing = []
+            if not values.get('client_id'):
+                missing.append('client_id')
+            if not values.get('client_secret'):
+                missing.append('client_secret')
+            if not values.get('token_url'):
+                missing.append('token_url')
+            if missing:
+                raise ValueError(f"OAuth is misconfigured; missing: {', '.join(missing)}")
+
+        # API key: if auth_type is custom, custom_header_name must be present
+        auth_type = values.get('auth_type')
+        if isinstance(auth_type, str) and auth_type.strip().lower() == 'custom' and values.get('api_key'):
+            if not values.get('custom_header_name'):
+                raise ValueError("custom_header_name is required when auth_type='custom'")
+
+        return values
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Validate the OpenAPI configuration by testing connectivity where possible.
+        
+        Validation behavior by authentication type:
+        
+        1. ANONYMOUS (no auth fields configured):
+           - Cannot validate without making actual API calls
+           - Returns None (success) - validation skipped
+           
+        2. API KEY (api_key field configured):
+           - Cannot validate without knowing which endpoint to call
+           - The OpenAPI spec is not available at configuration time
+           - Returns None (success) - validation skipped
+           
+        3. OAUTH2 CLIENT CREDENTIALS (client_id, client_secret, token_url configured):
+           - CAN validate by attempting token exchange with the OAuth provider
+           - Makes a real HTTP request to token_url
+           - Returns None on success, error message on failure
+        
+        Args:
+            settings: Dictionary containing OpenAPI configuration fields
+        
+        Returns:
+            None: Configuration is valid (or cannot be validated for this auth type)
+            str: Error message describing the validation failure
+        """
+        
+        # =====================================================================
+        # Determine authentication type from configured fields
+        # =====================================================================
+        
+        client_id = settings.get('client_id')
+        client_secret = settings.get('client_secret')
+        token_url = settings.get('token_url')
+        
+        has_oauth_fields = client_id or client_secret or token_url
+        
+        # =====================================================================
+        # ANONYMOUS or API KEY: Cannot validate, return success
+        # =====================================================================
+        
+        if not has_oauth_fields:
+            # No OAuth fields configured - this is either:
+            # - Anonymous authentication (no auth at all)
+            # - API Key authentication (api_key field may be set)
+            # 
+            # Neither can be validated without making actual API calls to the
+            # target service, and we don't have the OpenAPI spec available here.
+            return None
+        
+        # =====================================================================
+        # OAUTH2: Validate by attempting token exchange
+        # =====================================================================
+        
+        # Check for required OAuth fields
+        if not client_id:
+            return "OAuth client_id is required when using OAuth authentication"
+        if not client_secret:
+            return "OAuth client_secret is required when using OAuth authentication"
+        if not token_url:
+            return "OAuth token_url is required when using OAuth authentication"
+        
+        # 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 str(client_secret).strip():
+            return "OAuth client_secret cannot be empty"
+        
+        # Validate token_url format
+        token_url = token_url.strip()
+        if not token_url.startswith(('http://', 'https://')):
+            return "OAuth token_url must start with http:// or https://"
+        
+        # Get optional OAuth settings
+        scope = settings.get('scope')
+        method = settings.get('method', 'default') or 'default'
+        
+        # ---------------------------------------------------------------------
+        # Attempt OAuth2 Client Credentials token exchange
+        # ---------------------------------------------------------------------
+        
+        try:
+            headers = {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                'Accept': 'application/json',
+            }
+            
+            data = {
+                'grant_type': 'client_credentials',
+            }
+            
+            # Apply credentials based on method
+            if method == 'Basic':
+                # Basic method: credentials in Authorization header (Spotify, some AWS)
+                credentials = f"{client_id}:{client_secret}"
+                encoded = base64.b64encode(credentials.encode('utf-8')).decode('utf-8')
+                headers['Authorization'] = f'Basic {encoded}'
+            else:
+                # Default method: credentials in POST body (Azure AD, Auth0, most providers)
+                data['client_id'] = client_id
+                data['client_secret'] = str(client_secret)
+            
+            if scope:
+                data['scope'] = scope
+            
+            response = requests.post(
+                token_url,
+                headers=headers,
+                data=data,
+                timeout=30,
+            )
+            
+            # ---------------------------------------------------------------------
+            # Handle response
+            # ---------------------------------------------------------------------
+            
+            if response.status_code == 200:
+                try:
+                    token_data = response.json()
+                    if 'access_token' in token_data:
+                        return None  # Success - token obtained
+                    return "OAuth response did not contain 'access_token'"
+                except Exception:
+                    return "Failed to parse OAuth token response"
+            
+            # Handle common error status codes with helpful messages
+            if response.status_code == 400:
+                try:
+                    error_data = response.json()
+                    error = error_data.get('error', 'bad_request')
+                    error_desc = error_data.get('error_description', '')
+                    if error_desc:
+                        return f"OAuth error: {error} - {error_desc}"
+                    return f"OAuth error: {error}"
+                except Exception:
+                    return "OAuth request failed: bad request (400)"
+            
+            if response.status_code == 401:
+                return "OAuth authentication failed: invalid client_id or client_secret"
+            
+            if response.status_code == 403:
+                return "OAuth access forbidden: client may lack required permissions"
+            
+            if response.status_code == 404:
+                return f"OAuth token endpoint not found: {token_url}"
+            
+            return f"OAuth token request failed with status {response.status_code}"
+            
+        except requests.exceptions.SSLError as e:
+            error_str = str(e).lower()
+            if 'hostname mismatch' in error_str:
+                return "OAuth token_url hostname does not match SSL certificate - verify the URL is correct"
+            if 'certificate verify failed' in error_str:
+                return "SSL certificate verification failed for OAuth endpoint - the server may have an invalid or self-signed certificate"
+            if 'certificate has expired' in error_str:
+                return "SSL certificate has expired for OAuth endpoint"
+            return "SSL error connecting to OAuth endpoint - verify the token_url is correct"
+        except requests.exceptions.ConnectionError as e:
+            error_str = str(e).lower()
+            if 'name or service not known' in error_str or 'nodename nor servname provided' in error_str:
+                return "OAuth token_url hostname could not be resolved - verify the URL is correct"
+            if 'connection refused' in error_str:
+                return "Connection refused by OAuth endpoint - verify the token_url and port are correct"
+            return "Cannot connect to OAuth token endpoint - verify the token_url is correct"
+        except requests.exceptions.Timeout:
+            return "OAuth token request timed out - the endpoint may be unreachable"
+        except requests.exceptions.RequestException:
+            return "OAuth request failed - verify the token_url is correct and accessible"
+        except Exception:
+            return "Unexpected error during OAuth configuration validation"

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)}"