tallyfy 1.0.3__py3-none-any.whl → 1.0.5__py3-none-any.whl

tallyfy/task_management/creation.py

@@ -0,0 +1,221 @@
+"""
+Task creation operations
+"""
+
+from typing import Optional
+from .base import TaskManagerBase
+from ..models import Task, TaskOwners, TallyfyError
+from email_validator import validate_email, EmailNotValidError
+
+
+class TaskCreation(TaskManagerBase):
+    """Handles task creation operations"""
+
+    def create_task(self, org_id: str, title: str, deadline: str,
+                   owners: TaskOwners, description: Optional[str] = None,
+                   max_assignable: Optional[int] = None, prevent_guest_comment: Optional[bool] = None) -> Optional[Task]:
+        """
+        Create a standalone task in the organization.
+
+        Args:
+            org_id: Organization ID
+            title: Task name (required)
+            deadline: Task deadline in "YYYY-mm-dd HH:ii:ss" format
+            owners: TaskOwners object with users, guests, and groups
+            description: Task description (optional)
+            max_assignable: Maximum number of assignees (optional)
+            prevent_guest_comment: Prevent guests from commenting (optional)
+
+        Returns:
+            Task object for the created task
+
+        Raises:
+            TallyfyError: If the request fails
+            ValueError: If required parameters are missing or invalid
+        """
+        self._validate_org_id(org_id)
+        
+        if not title or not isinstance(title, str):
+            raise ValueError("Task title must be a non-empty string")
+
+        if not deadline or not isinstance(deadline, str):
+            raise ValueError("Task deadline must be a non-empty string in 'YYYY-mm-dd HH:ii:ss' format")
+
+        # Validate that at least one assignee is provided
+        if not owners or not isinstance(owners, TaskOwners):
+            raise ValueError("TaskOwners object is required")
+            
+        if not owners.users and not owners.guests and not owners.groups:
+            raise ValueError("At least one assignee is required (users, guests, or groups)")
+
+        # Validate max_assignable if provided
+        if max_assignable is not None and (not isinstance(max_assignable, int) or max_assignable <= 0):
+            raise ValueError("max_assignable must be a positive integer")
+
+        try:
+            endpoint = f"organizations/{org_id}/tasks"
+
+            task_data = {
+                "title": title,
+                "deadline": deadline,
+                "owners": {
+                    "users": owners.users or [],
+                    "guests": owners.guests or [],
+                    "groups": owners.groups or []
+                },
+                "task_type": "task",
+                "separate_task_for_each_assignee": True,
+                "status": "not-started",
+                "everyone_must_complete": False,
+                "is_soft_start_date": True
+            }
+
+            # Add optional fields
+            if description:
+                task_data["description"] = description
+            if max_assignable is not None:
+                task_data["max_assignable"] = max_assignable
+            if prevent_guest_comment is not None:
+                task_data["prevent_guest_comment"] = prevent_guest_comment
+
+            response_data = self.sdk._make_request('POST', endpoint, data=task_data)
+
+            task_response_data = self._extract_data(response_data)
+            if task_response_data:
+                # Handle both single task and list responses
+                if isinstance(task_response_data, list) and task_response_data:
+                    return Task.from_dict(task_response_data[0])
+                elif isinstance(task_response_data, dict):
+                    return Task.from_dict(task_response_data)
+            
+            # Check if response_data itself is the task data
+            if isinstance(response_data, dict) and 'data' in response_data:
+                task_data_response = response_data['data']
+                if isinstance(task_data_response, dict):
+                    return Task.from_dict(task_data_response)
+            
+            self.sdk.logger.warning("Unexpected response format for task creation")
+            return None
+
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "create task", org_id=org_id, title=title)
+
+    def create_simple_task(self, org_id: str, title: str, deadline: str, user_ids: Optional[list] = None, 
+                          guest_emails: Optional[list] = None, group_ids: Optional[list] = None,
+                          description: Optional[str] = None) -> Optional[Task]:
+        """
+        Create a simple task with basic assignee information.
+        
+        This is a convenience method that creates TaskOwners internally.
+
+        Args:
+            org_id: Organization ID
+            title: Task name (required)
+            deadline: Task deadline in "YYYY-mm-dd HH:ii:ss" format
+            user_ids: List of user IDs to assign (optional)
+            guest_emails: List of guest email addresses to assign (optional)
+            group_ids: List of group IDs to assign (optional)
+            description: Task description (optional)
+
+        Returns:
+            Task object for the created task
+
+        Raises:
+            TallyfyError: If the request fails
+            ValueError: If required parameters are missing or no assignees provided
+        """
+        # Validate that at least one assignee type is provided
+        if not user_ids and not guest_emails and not group_ids:
+            raise ValueError("At least one assignee is required (user_ids, guest_emails, or group_ids)")
+
+        # Create TaskOwners object
+        owners = TaskOwners(
+            users=user_ids or [],
+            guests=guest_emails or [],
+            groups=group_ids or []
+        )
+
+        return self.create_task(org_id, title, deadline, owners, description)
+
+    def create_user_task(self, org_id: str, title: str, deadline: str, user_ids: list, 
+                        description: Optional[str] = None) -> Optional[Task]:
+        """
+        Create a task assigned to specific users only.
+
+        Args:
+            org_id: Organization ID
+            title: Task name (required)
+            deadline: Task deadline in "YYYY-mm-dd HH:ii:ss" format
+            user_ids: List of user IDs to assign (required)
+            description: Task description (optional)
+
+        Returns:
+            Task object for the created task
+
+        Raises:
+            TallyfyError: If the request fails
+            ValueError: If required parameters are missing
+        """
+        if not user_ids or not isinstance(user_ids, list):
+            raise ValueError("user_ids must be a non-empty list")
+
+        return self.create_simple_task(org_id, title, deadline, user_ids=user_ids, description=description)
+
+    def create_guest_task(self, org_id: str, title: str, deadline: str, guest_emails: list, 
+                         description: Optional[str] = None) -> Optional[Task]:
+        """
+        Create a task assigned to guests only.
+
+        Args:
+            org_id: Organization ID
+            title: Task name (required)
+            deadline: Task deadline in "YYYY-mm-dd HH:ii:ss" format
+            guest_emails: List of guest email addresses to assign (required)
+            description: Task description (optional)
+
+        Returns:
+            Task object for the created task
+
+        Raises:
+            TallyfyError: If the request fails
+            ValueError: If required parameters are missing
+        """
+        if not guest_emails or not isinstance(guest_emails, list):
+            raise ValueError("guest_emails must be a non-empty list")
+
+        # Basic email validation
+        for email in guest_emails:
+            try:
+                validation = validate_email(email)
+                # The validated email address
+                email = validation.normalized
+            except EmailNotValidError as e:
+                raise ValueError(f"Invalid email address: {str(e)}")
+
+        return self.create_simple_task(org_id, title, deadline, guest_emails=guest_emails, description=description)
+
+    def create_group_task(self, org_id: str, title: str, deadline: str, group_ids: list, 
+                         description: Optional[str] = None) -> Optional[Task]:
+        """
+        Create a task assigned to groups only.
+
+        Args:
+            org_id: Organization ID
+            title: Task name (required)
+            deadline: Task deadline in "YYYY-mm-dd HH:ii:ss" format
+            group_ids: List of group IDs to assign (required)
+            description: Task description (optional)
+
+        Returns:
+            Task object for the created task
+
+        Raises:
+            TallyfyError: If the request fails
+            ValueError: If required parameters are missing
+        """
+        if not group_ids or not isinstance(group_ids, list):
+            raise ValueError("group_ids must be a non-empty list")
+
+        return self.create_simple_task(org_id, title, deadline, group_ids=group_ids, description=description)

tallyfy/task_management/retrieval.py

@@ -0,0 +1,211 @@
+"""
+Task and process retrieval operations
+"""
+
+from typing import List, Optional
+from .base import TaskManagerBase
+from ..models import Task, Run, TallyfyError
+
+
+class TaskRetrieval(TaskManagerBase):
+    """Handles task and process retrieval operations"""
+
+    def get_my_tasks(self, org_id: str) -> List[Task]:
+        """
+        Get all tasks assigned to the current user in the organization.
+
+        Args:
+            org_id: Organization ID
+
+        Returns:
+            List of Task objects assigned to the current user
+
+        Raises:
+            TallyfyError: If the request fails
+        """
+        self._validate_org_id(org_id)
+        
+        try:
+            endpoint = f"organizations/{org_id}/me/tasks"
+            response_data = self.sdk._make_request('GET', endpoint)
+
+            tasks_data = self._extract_data(response_data)
+            if tasks_data:
+                return [Task.from_dict(task_data) for task_data in tasks_data]
+            else:
+                self.sdk.logger.warning("Unexpected response format for tasks")
+                return []
+
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "get my tasks", org_id=org_id)
+
+    def get_user_tasks(self, org_id: str, user_id: int) -> List[Task]:
+        """
+        Get all tasks assigned to the given user in the organization.
+
+        Args:
+            org_id: Organization ID
+            user_id: User ID
+
+        Returns:
+            List of Task objects assigned to the given user ID
+
+        Raises:
+            TallyfyError: If the request fails
+        """
+        self._validate_org_id(org_id)
+        self._validate_user_id(user_id)
+        
+        try:
+            endpoint = f"organizations/{org_id}/users/{user_id}/tasks"
+            params = {
+                'per_page': '100',
+                'sort_by': 'newest',
+                'status': 'all',
+                'with': 'run,threads_count,step,tags,folders,member_watchers.watcher'
+            }
+            
+            response_data = self.sdk._make_request('GET', endpoint, params=params)
+
+            tasks_data = self._extract_data(response_data)
+            if tasks_data:
+                return [Task.from_dict(task_data) for task_data in tasks_data]
+            else:
+                self.sdk.logger.warning("Unexpected response format for user tasks")
+                return []
+
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "get user tasks", org_id=org_id, user_id=user_id)
+
+    def get_tasks_for_process(self, org_id: str, process_id: Optional[str] = None, process_name: Optional[str] = None) -> List[Task]:
+        """
+        Get all tasks for a given process (run).
+
+        Args:
+            org_id: Organization ID
+            process_id: Process (run) ID to get tasks for
+            process_name: Process (run) name to get tasks for (alternative to process_id)
+
+        Returns:
+            List of Task objects for the specified process
+
+        Raises:
+            TallyfyError: If the request fails
+            ValueError: If neither process_id nor process_name is provided
+        """
+        self._validate_org_id(org_id)
+        
+        if not process_id and not process_name:
+            raise ValueError("Either process_id or process_name must be provided")
+        
+        try:
+            # If process_name is provided but not process_id, search for the process first
+            if process_name and not process_id:
+                # We need to import TaskSearch here to avoid circular imports
+                from .search import TaskSearch
+                search = TaskSearch(self.sdk)
+                process_id = search.search_processes_by_name(org_id, process_name)
+            
+            self._validate_process_id(process_id)
+            
+            endpoint = f"organizations/{org_id}/runs/{process_id}/tasks"
+            response_data = self.sdk._make_request('GET', endpoint)
+
+            tasks_data = self._extract_data(response_data)
+            if tasks_data:
+                return [Task.from_dict(task_data) for task_data in tasks_data]
+            else:
+                self.sdk.logger.warning("Unexpected response format for process tasks")
+                return []
+
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "get tasks for process", org_id=org_id, process_id=process_id, process_name=process_name)
+
+    def get_organization_runs(self, org_id: str, with_data: Optional[str] = None, 
+                            form_fields_values: Optional[bool] = None,
+                            owners: Optional[str] = None, task_status: Optional[str] = None,
+                            groups: Optional[str] = None, status: Optional[str] = None,
+                            folder: Optional[str] = None, checklist_id: Optional[str] = None,
+                            starred: Optional[bool] = None, run_type: Optional[str] = None,
+                            tag: Optional[str] = None) -> List[Run]:
+        """
+        Get all processes (runs) in the organization.
+
+        Args:
+            org_id: Organization ID
+            with_data: Comma-separated data to include (e.g., 'checklist,tasks,assets,tags')
+            form_fields_values: Include form field values
+            owners: Filter by specific member IDs
+            task_status: Filter by task status ('all', 'in-progress', 'completed')
+            groups: Filter by group IDs
+            status: Filter by process status ('active', 'problem', 'delayed', 'complete', 'archived')
+            folder: Filter by folder ID
+            checklist_id: Filter by template ID
+            starred: Filter by starred status
+            run_type: Filter by type ('procedure', 'form', 'document')
+            tag: Filter by tag ID
+
+        Returns:
+            List of Run objects
+
+        Raises:
+            TallyfyError: If the request fails
+        """
+        self._validate_org_id(org_id)
+        
+        try:
+            endpoint = f"organizations/{org_id}/runs"
+            
+            # Build parameters using base class helper
+            params = self._build_query_params(
+                with_=with_data,  # Use with_ to avoid Python keyword conflict
+                form_fields_values=form_fields_values,
+                owners=owners,
+                task_status=task_status,
+                groups=groups,
+                status=status,
+                folder=folder,
+                checklist_id=checklist_id,
+                starred=starred,
+                type=run_type,  # API expects 'type' parameter
+                tag=tag
+            )
+            
+            # Handle the 'with' parameter specially due to Python keyword conflict
+            if with_data:
+                params['with'] = with_data
+                if 'with_' in params:
+                    del params['with_']
+            
+            response_data = self.sdk._make_request('GET', endpoint, params=params)
+
+            runs_data = self._extract_data(response_data)
+            if runs_data:
+                return [Run.from_dict(run_data) for run_data in runs_data]
+            else:
+                self.sdk.logger.warning("Unexpected response format for organization runs")
+                return []
+
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "get organization runs", org_id=org_id)
+
+    def get_organization_processes(self, org_id: str, **kwargs) -> List[Run]:
+        """
+        Alias for get_organization_runs for better naming consistency.
+        
+        Args:
+            org_id: Organization ID
+            **kwargs: Same parameters as get_organization_runs
+            
+        Returns:
+            List of Run objects
+        """
+        return self.get_organization_runs(org_id, **kwargs)

tallyfy/task_management/search.py

@@ -0,0 +1,196 @@
+"""
+Task and process search operations
+"""
+
+from typing import List
+from .base import TaskManagerBase
+from ..models import SearchResult, TallyfyError
+
+
+class TaskSearch(TaskManagerBase):
+    """Handles task and process search operations"""
+
+    def search_processes_by_name(self, org_id: str, process_name: str) -> str:
+        """
+        Search for processes by name using the search endpoint.
+
+        Args:
+            org_id: Organization ID
+            process_name: Name or partial name of the process to search for
+
+        Returns:
+            Process ID of the found process
+
+        Raises:
+            TallyfyError: If no process found, multiple matches, or search fails
+        """
+        self._validate_org_id(org_id)
+        
+        if not process_name or not isinstance(process_name, str):
+            raise ValueError("Process name must be a non-empty string")
+        
+        try:
+            search_endpoint = f"organizations/{org_id}/search"
+            search_params = {
+                'on': 'process', 
+                'per_page': '20',
+                'search': process_name
+            }
+            
+            search_response = self.sdk._make_request('GET', search_endpoint, params=search_params)
+            
+            if isinstance(search_response, dict) and 'process' in search_response:
+                process_data = search_response['process']
+                if 'data' in process_data and process_data['data']:
+                    processes = process_data['data']
+                    
+                    # First try exact match (case-insensitive)
+                    exact_matches = [p for p in processes if p['name'].lower() == process_name.lower()]
+                    if exact_matches:
+                        return exact_matches[0]['id']
+                    elif len(processes) == 1:
+                        # Single search result, use it
+                        return processes[0]['id']
+                    else:
+                        # Multiple matches found, provide helpful error with options
+                        match_names = [f"'{p['name']}'" for p in processes[:5]]  # Show max 5
+                        raise TallyfyError(f"Multiple processes found matching '{process_name}': {', '.join(match_names)}. Please be more specific.")
+                else:
+                    raise TallyfyError(f"No process found matching name: {process_name}")
+            else:
+                raise TallyfyError(f"Search failed for process name: {process_name}")
+                
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "search processes by name", org_id=org_id, process_name=process_name)
+
+    def search(self, org_id: str, search_query: str, search_type: str = "process", per_page: int = 20) -> List[SearchResult]:
+        """
+        Search for processes, templates, or tasks in the organization.
+
+        Args:
+            org_id: Organization ID
+            search_query: Text to search for
+            search_type: Type of search - 'process', 'blueprint', or 'task' (default: 'process'). blueprint equals template
+            per_page: Number of results per page (default: 20)
+
+        Returns:
+            List of SearchResult objects
+
+        Raises:
+            TallyfyError: If the request fails
+            ValueError: If search_type is not valid
+        """
+        self._validate_org_id(org_id)
+        
+        if not search_query or not isinstance(search_query, str):
+            raise ValueError("Search query must be a non-empty string")
+        
+        # Validate search type
+        valid_types = ["process", "blueprint", "task"]
+        if search_type not in valid_types:
+            raise ValueError(f"Search type must be one of: {', '.join(valid_types)}")
+        
+        if per_page <= 0 or per_page > 100:
+            raise ValueError("per_page must be between 1 and 100")
+        
+        try:
+            endpoint = f"organizations/{org_id}/search"
+            params = {
+                'on': search_type,
+                'per_page': str(per_page),
+                'search': search_query
+            }
+            
+            response_data = self.sdk._make_request('GET', endpoint, params=params)
+            
+            search_data = self._extract_data(response_data, search_type)
+            if search_data:
+                return [SearchResult.from_dict(result_data, search_type) for result_data in search_data]
+            else:
+                self.sdk.logger.info(f"No {search_type} results found for query: {search_query}")
+                return []
+
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "search", org_id=org_id, search_query=search_query, search_type=search_type)
+
+    def search_processes(self, org_id: str, search_query: str, per_page: int = 20) -> List[SearchResult]:
+        """
+        Search for processes in the organization.
+
+        Args:
+            org_id: Organization ID
+            search_query: Text to search for
+            per_page: Number of results per page (default: 20)
+
+        Returns:
+            List of SearchResult objects for processes
+
+        Raises:
+            TallyfyError: If the request fails
+        """
+        return self.search(org_id, search_query, "process", per_page)
+
+    def search_templates(self, org_id: str, search_query: str, per_page: int = 20) -> List[SearchResult]:
+        """
+        Search for templates (blueprints) in the organization.
+
+        Args:
+            org_id: Organization ID
+            search_query: Text to search for
+            per_page: Number of results per page (default: 20)
+
+        Returns:
+            List of SearchResult objects for templates
+
+        Raises:
+            TallyfyError: If the request fails
+        """
+        return self.search(org_id, search_query, "blueprint", per_page)
+
+    def search_tasks(self, org_id: str, search_query: str, per_page: int = 20) -> List[SearchResult]:
+        """
+        Search for tasks in the organization.
+
+        Args:
+            org_id: Organization ID
+            search_query: Text to search for
+            per_page: Number of results per page (default: 20)
+
+        Returns:
+            List of SearchResult objects for tasks
+
+        Raises:
+            TallyfyError: If the request fails
+        """
+        return self.search(org_id, search_query, "task", per_page)
+
+    def find_process_by_name(self, org_id: str, process_name: str, exact_match: bool = True) -> List[SearchResult]:
+        """
+        Find processes by name with flexible matching options.
+
+        Args:
+            org_id: Organization ID
+            process_name: Name of the process to search for
+            exact_match: If True, only return exact matches (case-insensitive)
+
+        Returns:
+            List of SearchResult objects matching the criteria
+
+        Raises:
+            TallyfyError: If the request fails
+        """
+        results = self.search_processes(org_id, process_name)
+        
+        if exact_match:
+            # Filter for exact matches (case-insensitive)
+            exact_results = []
+            for result in results:
+                if hasattr(result, 'name') and result.name.lower() == process_name.lower():
+                    exact_results.append(result)
+            return exact_results
+        
+        return results