recce-cloud 1.32.0__py3-none-any.whl → 1.34.0__py3-none-any.whl

recce_cloud/VERSION

@@ -1 +1 @@
-1.32.0
+1.34.0

recce_cloud/api/base.py

@@ -74,7 +74,7 @@ class BaseRecceCloudClient(ABC):
         self,
         branch: str,
         adapter_type: str,
-        cr_number: Optional[int] = None,
+        pr_number: Optional[int] = None,
         commit_sha: Optional[str] = None,
         session_type: Optional[str] = None,
     ) -> Dict:
@@ -84,9 +84,9 @@ class BaseRecceCloudClient(ABC):
         Args:
             branch: Branch name
             adapter_type: DBT adapter type (e.g., 'postgres', 'snowflake', 'bigquery')
-            cr_number: Change request number (PR/MR number) for CR sessions
+            pr_number: Pull/Merge request number (PR/MR number) for PR sessions
             commit_sha: Commit SHA (GitLab requires this)
-            session_type: Session type ("cr", "prod", "dev") - determines if cr_number is used
+            session_type: Session type ("pr", "prod", "dev") - determines if pr_number is used
 
         Returns:
             Dictionary containing:
@@ -113,15 +113,15 @@ class BaseRecceCloudClient(ABC):
     @abstractmethod
     def get_session_download_urls(
         self,
-        cr_number: Optional[int] = None,
+        pr_number: Optional[int] = None,
         session_type: Optional[str] = None,
     ) -> Dict:
         """
         Get download URLs for artifacts from a session.
 
         Args:
-            cr_number: Change request number (PR/MR number) for CR sessions
-            session_type: Session type ("cr", "prod", "dev")
+            pr_number: Pull/Merge request number (PR/MR number) for PR sessions
+            session_type: Session type ("pr", "prod", "dev")
 
         Returns:
             Dictionary containing:
@@ -134,15 +134,15 @@ class BaseRecceCloudClient(ABC):
     @abstractmethod
     def delete_session(
         self,
-        cr_number: Optional[int] = None,
+        pr_number: Optional[int] = None,
         session_type: Optional[str] = None,
     ) -> Dict:
         """
         Delete a session.
 
         Args:
-            cr_number: Change request number (PR/MR number) for CR sessions
-            session_type: Session type ("cr", "prod") - "prod" deletes base session
+            pr_number: Pull/Merge request number (PR/MR number) for PR sessions
+            session_type: Session type ("pr", "prod") - "prod" deletes base session
 
         Returns:
             Dictionary containing:

recce_cloud/api/client.py

@@ -1,13 +1,13 @@
 """
 Recce Cloud API clients for lightweight operations.
 
-Provides clients for session management and report generation.
+Provides clients for session management, organization/project listing, and report generation.
 """
 
 import json
 import logging
 import os
-from typing import Optional
+from typing import Any, Dict, List, Optional
 
 import requests
 
@@ -42,6 +42,24 @@ class RecceCloudClient:
         }
         return requests.request(method, url, headers=headers, **kwargs)
 
+    def _safe_get_error_detail(self, response, default: str) -> str:
+        """Safely extract error detail from response JSON.
+
+        Some error responses may not have a valid JSON body (e.g., HTML error pages
+        from proxies), so we need to handle JSONDecodeError gracefully.
+
+        Args:
+            response: The HTTP response object.
+            default: Default message to return if JSON parsing fails.
+
+        Returns:
+            The error detail string from the response, or the default message.
+        """
+        try:
+            return response.json().get("detail", default)
+        except (json.JSONDecodeError, ValueError):
+            return default
+
     def _replace_localhost_with_docker_internal(self, url: str) -> str:
         """Convert localhost URLs to docker internal URLs if running in Docker."""
         if url is None:
@@ -75,7 +93,7 @@ class RecceCloudClient:
         api_url = f"{self.base_url_v2}/sessions/{session_id}"
         response = self._request("GET", api_url)
         if response.status_code == 403:
-            return {"status": "error", "message": response.json().get("detail")}
+            return {"status": "error", "message": self._safe_get_error_detail(response, "Permission denied")}
         if response.status_code != 200:
             raise RecceCloudException(
                 reason=response.text,
@@ -181,7 +199,7 @@ class RecceCloudClient:
         data = {"adapter_type": adapter_type}
         response = self._request("PATCH", api_url, json=data)
         if response.status_code == 403:
-            return {"status": "error", "message": response.json().get("detail")}
+            return {"status": "error", "message": self._safe_get_error_detail(response, "Permission denied")}
         if response.status_code != 200:
             raise RecceCloudException(
                 reason=response.text,
@@ -211,7 +229,7 @@ class RecceCloudClient:
             return True
         if response.status_code == 403:
             raise RecceCloudException(
-                reason=response.json().get("detail", "Permission denied"),
+                reason=self._safe_get_error_detail(response, "Permission denied"),
                 status_code=response.status_code,
             )
         if response.status_code == 404:
@@ -247,7 +265,7 @@ class RecceCloudClient:
             return response.json()
         if response.status_code == 403:
             raise RecceCloudException(
-                reason=response.json().get("detail", "Permission denied"),
+                reason=self._safe_get_error_detail(response, "Permission denied"),
                 status_code=response.status_code,
             )
         if response.status_code == 404:
@@ -260,6 +278,483 @@ class RecceCloudClient:
             status_code=response.status_code,
         )
 
+    def list_organizations(self) -> List[Dict[str, Any]]:
+        """
+        List all organizations the user has access to.
+
+        Returns:
+            List of organization dictionaries with id, name, slug fields.
+
+        Raises:
+            RecceCloudException: If the API call fails.
+        """
+        api_url = f"{self.base_url_v2}/organizations"
+        response = self._request("GET", api_url)
+
+        if response.status_code != 200:
+            raise RecceCloudException(
+                reason=response.text,
+                status_code=response.status_code,
+            )
+
+        data = response.json()
+        return data.get("organizations", [])
+
+    def list_projects(self, org_id: str) -> List[Dict[str, Any]]:
+        """
+        List all projects in an organization.
+
+        Args:
+            org_id: Organization ID or slug.
+
+        Returns:
+            List of project dictionaries with id, name, slug fields.
+
+        Raises:
+            RecceCloudException: If the API call fails.
+        """
+        api_url = f"{self.base_url_v2}/organizations/{org_id}/projects"
+        response = self._request("GET", api_url)
+
+        if response.status_code != 200:
+            raise RecceCloudException(
+                reason=response.text,
+                status_code=response.status_code,
+            )
+
+        data = response.json()
+        return data.get("projects", [])
+
+    def get_organization(self, org_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get a specific organization by ID or slug.
+
+        Args:
+            org_id: Organization ID or slug.
+
+        Returns:
+            Organization dictionary, or None if not found.
+
+        Raises:
+            RecceCloudException: If the API call fails.
+        """
+        orgs = self.list_organizations()
+        for org in orgs:
+            # Compare as strings to handle both int and str IDs
+            if str(org.get("id")) == str(org_id) or org.get("slug") == org_id or org.get("name") == org_id:
+                return org
+        return None
+
+    def get_project(self, org_id: str, project_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get a specific project by ID or slug.
+
+        Args:
+            org_id: Organization ID or slug.
+            project_id: Project ID or slug.
+
+        Returns:
+            Project dictionary, or None if not found.
+
+        Raises:
+            RecceCloudException: If the API call fails.
+        """
+        projects = self.list_projects(org_id)
+        for project in projects:
+            # Compare as strings to handle both int and str IDs
+            if (
+                str(project.get("id")) == str(project_id)
+                or project.get("slug") == project_id
+                or project.get("name") == project_id
+            ):
+                return project
+        return None
+
+    def list_sessions(
+        self,
+        org_id: str,
+        project_id: str,
+        session_name: Optional[str] = None,
+        session_type: Optional[str] = None,
+        branch: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        List sessions in a project with optional filtering.
+
+        Args:
+            org_id: Organization ID or slug.
+            project_id: Project ID or slug.
+            session_name: Filter by session name (exact match).
+            session_type: Filter by session type (e.g., "pr", "prod", "manual").
+            branch: Filter by branch name (exact match).
+            limit: Maximum number of results to return (1-1000).
+            offset: Number of results to skip for pagination.
+
+        Returns:
+            List of session dictionaries.
+
+        Raises:
+            RecceCloudException: If the API call fails.
+        """
+        api_url = f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions"
+        params = {}
+        if session_name:
+            params["name"] = session_name
+        if session_type:
+            params["type"] = session_type
+        if branch:
+            params["branch"] = branch
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+
+        response = self._request("GET", api_url, params=params if params else None)
+
+        if response.status_code == 404:
+            raise RecceCloudException(
+                reason="Organization or project not found",
+                status_code=response.status_code,
+            )
+        if response.status_code != 200:
+            raise RecceCloudException(
+                reason=response.text,
+                status_code=response.status_code,
+            )
+
+        data = response.json()
+        return data.get("sessions", [])
+
+    def get_session_by_name(
+        self,
+        org_id: str,
+        project_id: str,
+        session_name: str,
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Get a session by its name.
+
+        Uses the list sessions endpoint with filtering to find a session
+        by name, which is unique within a project.
+
+        Args:
+            org_id: Organization ID or slug.
+            project_id: Project ID or slug.
+            session_name: The session name to look up.
+
+        Returns:
+            Session dictionary if found, None otherwise.
+
+        Raises:
+            RecceCloudException: If the API call fails.
+        """
+        sessions = self.list_sessions(
+            org_id=org_id,
+            project_id=project_id,
+            session_name=session_name,
+            limit=1,
+        )
+        if sessions:
+            return sessions[0]
+        return None
+
+    def create_session(
+        self,
+        org_id: str,
+        project_id: str,
+        session_name: str,
+        adapter_type: Optional[str] = None,
+        session_type: str = "manual",
+    ) -> Dict[str, Any]:
+        """
+        Create a new session with the given name.
+
+        Args:
+            org_id: Organization ID or slug.
+            project_id: Project ID or slug.
+            session_name: The name for the new session.
+            adapter_type: dbt adapter type (e.g., "postgres", "snowflake").
+            session_type: Session type (default: "manual").
+
+        Returns:
+            Created session dictionary with id, name, and other fields.
+
+        Raises:
+            RecceCloudException: If the API call fails or session creation fails.
+        """
+        api_url = f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions"
+        data = {
+            "name": session_name,
+            "type": session_type,
+        }
+        if adapter_type:
+            data["adapter_type"] = adapter_type
+
+        response = self._request("POST", api_url, json=data)
+
+        if response.status_code == 404:
+            raise RecceCloudException(
+                reason="Organization or project not found",
+                status_code=response.status_code,
+            )
+        if response.status_code == 409:
+            raise RecceCloudException(
+                reason=f"Session with name '{session_name}' already exists",
+                status_code=response.status_code,
+            )
+        if response.status_code == 403:
+            raise RecceCloudException(
+                reason=self._safe_get_error_detail(response, "Permission denied"),
+                status_code=response.status_code,
+            )
+        if response.status_code not in [200, 201]:
+            raise RecceCloudException(
+                reason=response.text,
+                status_code=response.status_code,
+            )
+
+        result = response.json()
+        # Handle both direct session response and wrapped response
+        if "session" in result:
+            return result["session"]
+        return result
+
+    def check_prerequisites(
+        self,
+        org_id: str,
+        project_id: str,
+        session_id: str,
+    ) -> Dict[str, Any]:
+        """
+        Check prerequisites for data review generation.
+
+        This calls the backend API to verify:
+        1. Session exists and belongs to the project
+        2. Session has artifacts uploaded (adapter_type is set)
+        3. Base session exists for the project
+        4. Base session has artifacts uploaded
+
+        Args:
+            org_id: Organization ID or slug.
+            project_id: Project ID or slug.
+            session_id: Session ID to check.
+
+        Returns:
+            dict with:
+                - success: bool
+                - session_id: str
+                - session_name: str
+                - adapter_type: str or None
+                - has_base_session: bool
+                - base_session_has_artifacts: bool
+                - is_ready: bool
+                - reason: str or None (explains why not ready)
+
+        Raises:
+            RecceCloudException: If the API call fails.
+        """
+        api_url = (
+            f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions/{session_id}/check-prerequisites"
+        )
+        response = self._request("GET", api_url)
+
+        if response.status_code == 404:
+            error_detail = "Session or project not found"
+            try:
+                error_detail = response.json().get("detail", error_detail)
+            except Exception:
+                pass
+            raise RecceCloudException(
+                reason=error_detail,
+                status_code=response.status_code,
+            )
+        if response.status_code == 400:
+            raise RecceCloudException(
+                reason=self._safe_get_error_detail(response, "Bad request"),
+                status_code=response.status_code,
+            )
+        if response.status_code == 403:
+            raise RecceCloudException(
+                reason=self._safe_get_error_detail(response, "Permission denied"),
+                status_code=response.status_code,
+            )
+        if response.status_code != 200:
+            raise RecceCloudException(
+                reason=response.text,
+                status_code=response.status_code,
+            )
+
+        return response.json()
+
+    def generate_data_review(
+        self,
+        org_id: str,
+        project_id: str,
+        session_id: str,
+        regenerate: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Trigger data review generation for a session.
+
+        Args:
+            org_id: Organization ID or slug.
+            project_id: Project ID or slug.
+            session_id: Session ID to generate review for.
+            regenerate: If True, regenerate even if a review already exists.
+
+        Returns:
+            dict with task_id if a new task was created, or empty if review already exists.
+
+        Raises:
+            RecceCloudException: If the API call fails.
+        """
+        api_url = f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions/{session_id}/recce_summary"
+        data = {"regenerate": regenerate}
+
+        response = self._request("POST", api_url, json=data)
+
+        if response.status_code == 404:
+            raise RecceCloudException(
+                reason="Session not found",
+                status_code=response.status_code,
+            )
+        if response.status_code == 403:
+            raise RecceCloudException(
+                reason=self._safe_get_error_detail(response, "Permission denied"),
+                status_code=response.status_code,
+            )
+        if response.status_code == 400:
+            raise RecceCloudException(
+                reason=self._safe_get_error_detail(response, "Bad request"),
+                status_code=response.status_code,
+            )
+        if response.status_code not in [200, 201, 202]:
+            raise RecceCloudException(
+                reason=response.text,
+                status_code=response.status_code,
+            )
+
+        return response.json()
+
+    def get_data_review(
+        self,
+        org_id: str,
+        project_id: str,
+        session_id: str,
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Get the existing data review for a session.
+
+        Args:
+            org_id: Organization ID or slug.
+            project_id: Project ID or slug.
+            session_id: Session ID to get review for.
+
+        Returns:
+            dict with session_id, session_name, summary (content), trace_id if found.
+            None if no review exists.
+
+        Raises:
+            RecceCloudException: If the API call fails.
+        """
+        api_url = f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions/{session_id}/recce_summary"
+        response = self._request("GET", api_url)
+
+        if response.status_code == 404:
+            # No review exists for this session
+            return None
+        if response.status_code == 403:
+            raise RecceCloudException(
+                reason=self._safe_get_error_detail(response, "Permission denied"),
+                status_code=response.status_code,
+            )
+        if response.status_code != 200:
+            raise RecceCloudException(
+                reason=response.text,
+                status_code=response.status_code,
+            )
+
+        return response.json()
+
+    def get_running_task(
+        self,
+        org_id: str,
+        project_id: str,
+        session_id: str,
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Get the currently running task for a session.
+
+        Args:
+            org_id: Organization ID or slug.
+            project_id: Project ID or slug.
+            session_id: Session ID to check.
+
+        Returns:
+            dict with task_id and status if a task is running, None otherwise.
+
+        Raises:
+            RecceCloudException: If the API call fails.
+        """
+        api_url = f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions/{session_id}/running_task"
+        response = self._request("GET", api_url)
+
+        if response.status_code == 404:
+            return None
+        if response.status_code == 403:
+            raise RecceCloudException(
+                reason=self._safe_get_error_detail(response, "Permission denied"),
+                status_code=response.status_code,
+            )
+        if response.status_code != 200:
+            raise RecceCloudException(
+                reason=response.text,
+                status_code=response.status_code,
+            )
+
+        data = response.json()
+        # Return None if no task is running
+        if data.get("task_id") is None:
+            return None
+        return data
+
+    def get_task_status(self, org_id: str, task_id: str) -> Dict[str, Any]:
+        """
+        Get the status of a task by ID.
+
+        Args:
+            org_id: Organization ID or slug.
+            task_id: Task ID to check.
+
+        Returns:
+            dict with id, command, status, created_at, started_at, finished_at, metadata.
+
+        Raises:
+            RecceCloudException: If the API call fails or task not found.
+        """
+        api_url = f"{self.base_url_v2}/organizations/{org_id}/tasks/{task_id}/status"
+        response = self._request("GET", api_url)
+
+        if response.status_code == 404:
+            raise RecceCloudException(
+                reason="Task not found",
+                status_code=response.status_code,
+            )
+        if response.status_code == 403:
+            raise RecceCloudException(
+                reason=self._safe_get_error_detail(response, "Permission denied"),
+                status_code=response.status_code,
+            )
+        if response.status_code != 200:
+            raise RecceCloudException(
+                reason=response.text,
+                status_code=response.status_code,
+            )
+
+        return response.json()
+
 
 class ReportClient:
     """Client for fetching reports from Recce Cloud API."""