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

tallyfy/__init__.py

@@ -4,17 +4,21 @@ Tallyfy SDK - A modular Python SDK for Tallyfy API
 
 from .core import TallyfySDK, TallyfyError
 from .models import *
-from .user_management import UserManagement
-from .task_management import TaskManagement
-from .template_management import TemplateManagement
-from .form_fields_management import FormFieldManagement
+from .user_management import UserManager, UserManagement
+from .task_management import TaskManager, TaskManagement
+from .template_management import TemplateManager, TemplateManagement
+from .form_fields_management import FormFieldManager, FormFieldManagement
 
 __version__ = "1.0.0"
 __all__ = [
     "TallyfySDK",
     "TallyfyError",
+    "UserManager",
     "UserManagement", 
+    "TaskManager",
     "TaskManagement",
+    "TemplateManager",
     "TemplateManagement",
+    "FormFieldManager",
     "FormFieldManagement"
 ]

tallyfy/core.py

@@ -148,15 +148,15 @@ class TallyfySDK(BaseSDK):
         super().__init__(api_key, base_url, timeout, max_retries, retry_delay)
         
         # Initialize management modules
-        from .user_management import UserManagement
-        from .task_management import TaskManagement  
-        from .template_management import TemplateManagement
-        from .form_fields_management import FormFieldManagement
+        from .user_management import UserManager
+        from .task_management import TaskManager  
+        from .template_management import TemplateManager
+        from .form_fields_management import FormFieldManager
         
-        self.users = UserManagement(self)
-        self.tasks = TaskManagement(self)
-        self.templates = TemplateManagement(self)
-        self.form_fields = FormFieldManagement(self)
+        self.users = UserManager(self)
+        self.tasks = TaskManager(self)
+        self.templates = TemplateManager(self)
+        self.form_fields = FormFieldManager(self)
 
     # Backward compatibility methods - delegate to management modules
     def get_organization_users(self, org_id: str, with_groups: bool = False):

tallyfy/form_fields_management/__init__.py

@@ -0,0 +1,70 @@
+"""
+Form Fields Management Package
+
+This package provides a refactored, modular approach to form field management
+functionality, breaking down the monolithic FormFieldManagement class into
+specialized components for better maintainability and separation of concerns.
+
+Classes:
+    FormFieldCRUD: Basic CRUD operations for form fields
+    FormFieldOptions: Dropdown options management  
+    FormFieldSuggestions: AI-powered form field suggestions
+    FormFieldManager: Unified interface combining all functionality
+"""
+
+from .base import FormFieldManagerBase
+from .crud_operations import FormFieldCRUD
+from .options_management import FormFieldOptions
+from .suggestions import FormFieldSuggestions
+
+
+class FormFieldManager:
+    """
+    Unified interface for form field management functionality.
+    
+    This class provides access to all form field management capabilities
+    through a single interface while maintaining the modular structure
+    underneath.
+    """
+    
+    def __init__(self, sdk):
+        """
+        Initialize form field manager with SDK instance.
+        
+        Args:
+            sdk: Main SDK instance
+        """
+        self.crud = FormFieldCRUD(sdk)
+        self.options = FormFieldOptions(sdk)
+        self.suggestions = FormFieldSuggestions(sdk)
+        
+        # For backward compatibility, expose common methods at the top level
+        self.add_form_field_to_step = self.crud.add_form_field_to_step
+        self.update_form_field = self.crud.update_form_field
+        self.move_form_field = self.crud.move_form_field
+        self.delete_form_field = self.crud.delete_form_field
+        self.get_step = self.crud.get_step
+        
+        # Options management methods
+        self.get_dropdown_options = self.options.get_dropdown_options
+        self.update_dropdown_options = self.options.update_dropdown_options
+        self.add_dropdown_option = self.options.add_dropdown_option
+        self.remove_dropdown_option = self.options.remove_dropdown_option
+        self.reorder_dropdown_options = self.options.reorder_dropdown_options
+        
+        # Suggestions methods
+        self.suggest_form_fields_for_step = self.suggestions.suggest_form_fields_for_step
+        self.suggest_field_improvements = self.suggestions.suggest_field_improvements
+
+
+# For backward compatibility, create an alias
+FormFieldManagement = FormFieldManager
+
+__all__ = [
+    'FormFieldManagerBase',
+    'FormFieldCRUD', 
+    'FormFieldOptions',
+    'FormFieldSuggestions',
+    'FormFieldManager',
+    'FormFieldManagement'  # Backward compatibility alias
+]

tallyfy/form_fields_management/base.py

@@ -0,0 +1,109 @@
+"""
+Base class for form field management operations
+"""
+
+from typing import Optional
+from ..models import TallyfyError
+
+
+class FormFieldManagerBase:
+    """Base class providing common functionality for form field management"""
+    
+    def __init__(self, sdk):
+        """
+        Initialize base form field manager.
+        
+        Args:
+            sdk: Main SDK instance
+        """
+        self.sdk = sdk
+    
+    def _validate_org_id(self, org_id: str) -> None:
+        """
+        Validate organization ID parameter.
+        
+        Args:
+            org_id: Organization ID to validate
+            
+        Raises:
+            ValueError: If org_id is invalid
+        """
+        if not org_id or not isinstance(org_id, str):
+            raise ValueError("Organization ID must be a non-empty string")
+    
+    def _validate_template_id(self, template_id: str) -> None:
+        """
+        Validate template ID parameter.
+        
+        Args:
+            template_id: Template ID to validate
+            
+        Raises:
+            ValueError: If template_id is invalid
+        """
+        if not template_id or not isinstance(template_id, str):
+            raise ValueError("Template ID must be a non-empty string")
+    
+    def _validate_step_id(self, step_id: str) -> None:
+        """
+        Validate step ID parameter.
+        
+        Args:
+            step_id: Step ID to validate
+            
+        Raises:
+            ValueError: If step_id is invalid
+        """
+        if not step_id or not isinstance(step_id, str):
+            raise ValueError("Step ID must be a non-empty string")
+    
+    def _validate_field_id(self, field_id: str) -> None:
+        """
+        Validate field ID parameter.
+        
+        Args:
+            field_id: Field ID to validate
+            
+        Raises:
+            ValueError: If field_id is invalid
+        """
+        if not field_id or not isinstance(field_id, str):
+            raise ValueError("Field ID must be a non-empty string")
+    
+    def _extract_data(self, response_data) -> Optional[dict]:
+        """
+        Extract data from API response.
+        
+        Args:
+            response_data: Raw response from API
+            
+        Returns:
+            Extracted data dictionary or None
+        """
+        if isinstance(response_data, dict):
+            if 'data' in response_data:
+                return response_data['data']
+            return response_data
+        return None
+    
+    def _handle_api_error(self, error: Exception, operation: str, **context) -> None:
+        """
+        Handle API errors with context.
+        
+        Args:
+            error: The exception that occurred
+            operation: Description of the operation that failed
+            **context: Additional context for error logging
+        """
+        context_str = ", ".join([f"{k}={v}" for k, v in context.items()])
+        error_msg = f"Failed to {operation}"
+        if context_str:
+            error_msg += f" ({context_str})"
+        error_msg += f": {error}"
+        
+        self.sdk.logger.error(error_msg)
+        
+        if isinstance(error, TallyfyError):
+            raise error
+        else:
+            raise TallyfyError(error_msg)

tallyfy/form_fields_management/crud_operations.py

@@ -0,0 +1,234 @@
+"""
+CRUD operations for form field management
+"""
+
+from typing import Dict, Any, Optional
+from .base import FormFieldManagerBase
+from ..models import Capture, Step, TallyfyError
+
+
+class FormFieldCRUD(FormFieldManagerBase):
+    """Handles basic CRUD operations for form fields"""
+
+    def add_form_field_to_step(self, org_id: str, template_id: str, step_id: str, field_data: Dict[str, Any]) -> Optional[Capture]:
+        """
+        Add form fields (text, dropdown, date, etc.) to a step.
+        
+        Args:
+            org_id: Organization ID
+            template_id: Template ID
+            step_id: Step ID
+            field_data: Form field creation data including field_type, label, required, etc.
+            
+        Returns:
+            Created Capture object or None if creation failed
+            
+        Raises:
+            TallyfyError: If the request fails
+        """
+        self._validate_org_id(org_id)
+        self._validate_template_id(template_id)
+        self._validate_step_id(step_id)
+        
+        try:
+            endpoint = f"organizations/{org_id}/checklists/{template_id}/steps/{step_id}/captures"
+            
+            # Validate required fields
+            required_fields = ['field_type', 'label']
+            for field in required_fields:
+                if field not in field_data:
+                    raise ValueError(f"Missing required field: {field}")
+            
+            # Set defaults for optional fields
+            capture_data = {
+                'field_type': field_data['field_type'],
+                'label': field_data['label'],
+                'required': field_data.get('required', True),
+                'position': field_data.get('position', 1)
+            }
+            
+            # Add optional fields if provided
+            optional_fields = ['guidance', 'options', 'default_value', 'default_value_enabled']
+            for field in optional_fields:
+                if field in field_data:
+                    capture_data[field] = field_data[field]
+            
+            response_data = self.sdk._make_request('POST', endpoint, data=capture_data)
+            
+            extracted_data = self._extract_data(response_data)
+            if extracted_data:
+                return Capture.from_dict(extracted_data)
+            else:
+                self.sdk.logger.warning("Unexpected response format for form field creation")
+                return None
+                
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "add form field to step", org_id=org_id, template_id=template_id, step_id=step_id)
+
+    def update_form_field(self, org_id: str, template_id: str, step_id: str, field_id: str, **kwargs) -> Optional[Capture]:
+        """
+        Update form field properties, validation, options.
+        
+        Args:
+            org_id: Organization ID
+            template_id: Template ID
+            step_id: Step ID
+            field_id: Form field ID
+            **kwargs: Form field properties to update
+            
+        Returns:
+            Updated Capture object or None if update failed
+            
+        Raises:
+            TallyfyError: If the request fails
+        """
+        self._validate_org_id(org_id)
+        self._validate_template_id(template_id)
+        self._validate_step_id(step_id)
+        self._validate_field_id(field_id)
+        
+        try:
+            endpoint = f"organizations/{org_id}/checklists/{template_id}/steps/{step_id}/captures/{field_id}"
+            
+            # Build update data from kwargs
+            update_data = {}
+            allowed_fields = [
+                'field_type', 'label', 'guidance', 'position', 'required',
+                'options', 'default_value', 'default_value_enabled'
+            ]
+            
+            for field, value in kwargs.items():
+                if field in allowed_fields:
+                    update_data[field] = value
+                else:
+                    self.sdk.logger.warning(f"Ignoring unknown form field: {field}")
+            
+            if not update_data:
+                raise ValueError("No valid form field properties provided for update")
+            
+            response_data = self.sdk._make_request('PUT', endpoint, data=update_data)
+            
+            extracted_data = self._extract_data(response_data)
+            if extracted_data:
+                return Capture.from_dict(extracted_data)
+            else:
+                self.sdk.logger.warning("Unexpected response format for form field update")
+                return None
+                
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "update form field", org_id=org_id, template_id=template_id, step_id=step_id, field_id=field_id)
+
+    def move_form_field(self, org_id: str, template_id: str, from_step: str, field_id: str, to_step: str, position: int = 1) -> bool:
+        """
+        Move form field between steps.
+        
+        Args:
+            org_id: Organization ID
+            template_id: Template ID
+            from_step: Source step ID
+            field_id: Form field ID to move
+            to_step: Target step ID
+            position: Position in target step (default: 1)
+            
+        Returns:
+            True if move was successful
+            
+        Raises:
+            TallyfyError: If the request fails
+        """
+        self._validate_org_id(org_id)
+        self._validate_template_id(template_id)
+        self._validate_step_id(from_step)
+        self._validate_field_id(field_id)
+        self._validate_step_id(to_step)
+        
+        try:
+            endpoint = f"organizations/{org_id}/checklists/{template_id}/steps/{from_step}/captures/{field_id}/move"
+            
+            move_data = {
+                'to_step_id': to_step,
+                'position': position
+            }
+            
+            response_data = self.sdk._make_request('POST', endpoint, data=move_data)
+            
+            # Check if move was successful
+            return isinstance(response_data, dict) and response_data.get('success', False)
+            
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "move form field", org_id=org_id, template_id=template_id, from_step=from_step, field_id=field_id, to_step=to_step)
+
+    def delete_form_field(self, org_id: str, template_id: str, step_id: str, field_id: str) -> bool:
+        """
+        Delete a form field from a step.
+        
+        Args:
+            org_id: Organization ID
+            template_id: Template ID
+            step_id: Step ID
+            field_id: Form field ID
+            
+        Returns:
+            True if deletion was successful
+            
+        Raises:
+            TallyfyError: If the request fails
+        """
+        self._validate_org_id(org_id)
+        self._validate_template_id(template_id)
+        self._validate_step_id(step_id)
+        self._validate_field_id(field_id)
+        
+        try:
+            endpoint = f"organizations/{org_id}/checklists/{template_id}/steps/{step_id}/captures/{field_id}"
+            
+            response_data = self.sdk._make_request('DELETE', endpoint)
+            
+            # Check if deletion was successful
+            return isinstance(response_data, dict) and response_data.get('success', False)
+            
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "delete form field", org_id=org_id, template_id=template_id, step_id=step_id, field_id=field_id)
+
+    def get_step(self, org_id: str, template_id: str, step_id: str) -> Optional[Step]:
+        """
+        Get a specific step with its details.
+        
+        Args:
+            org_id: Organization ID
+            template_id: Template ID
+            step_id: Step ID
+            
+        Returns:
+            Step object or None if not found
+            
+        Raises:
+            TallyfyError: If the request fails
+        """
+        self._validate_org_id(org_id)
+        self._validate_template_id(template_id)
+        self._validate_step_id(step_id)
+        
+        try:
+            endpoint = f"organizations/{org_id}/checklists/{template_id}/steps/{step_id}"
+            response_data = self.sdk._make_request('GET', endpoint)
+            
+            extracted_data = self._extract_data(response_data)
+            if extracted_data:
+                return Step.from_dict(extracted_data)
+            else:
+                self.sdk.logger.warning("Unexpected response format for step")
+                return None
+                
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "get step", org_id=org_id, template_id=template_id, step_id=step_id)

tallyfy/form_fields_management/options_management.py

@@ -0,0 +1,222 @@
+"""
+Dropdown options management for form fields
+"""
+
+from typing import List, Dict, Any, Optional
+from .base import FormFieldManagerBase
+from ..models import TallyfyError
+
+
+class FormFieldOptions(FormFieldManagerBase):
+    """Handles dropdown options management for form fields"""
+
+    def get_dropdown_options(self, org_id: str, template_id: str, step_id: str, field_id: str) -> List[str]:
+        """
+        Get current dropdown options for analysis.
+        
+        Args:
+            org_id: Organization ID
+            template_id: Template ID
+            step_id: Step ID
+            field_id: Form field ID
+            
+        Returns:
+            List of dropdown option strings
+            
+        Raises:
+            TallyfyError: If the request fails
+        """
+        self._validate_org_id(org_id)
+        self._validate_template_id(template_id)
+        self._validate_step_id(step_id)
+        self._validate_field_id(field_id)
+        
+        try:
+            endpoint = f"organizations/{org_id}/checklists/{template_id}/steps/{step_id}/captures/{field_id}"
+            
+            response_data = self.sdk._make_request('GET', endpoint)
+            
+            extracted_data = self._extract_data(response_data)
+            if extracted_data:
+                options = extracted_data.get('options', [])
+                
+                # Extract option values/labels
+                if isinstance(options, list):
+                    return [
+                        opt.get('label', opt.get('value', str(opt))) if isinstance(opt, dict) else str(opt) 
+                        for opt in options
+                    ]
+                else:
+                    return []
+            else:
+                self.sdk.logger.warning("Unexpected response format for form field options")
+                return []
+                
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "get dropdown options", org_id=org_id, template_id=template_id, step_id=step_id, field_id=field_id)
+
+    def update_dropdown_options(self, org_id: str, template_id: str, step_id: str, field_id: str, options: List[str]) -> bool:
+        """
+        Update dropdown options (for external data integration).
+        
+        Args:
+            org_id: Organization ID
+            template_id: Template ID
+            step_id: Step ID
+            field_id: Form field ID
+            options: List of new option strings
+            
+        Returns:
+            True if update was successful
+            
+        Raises:
+            TallyfyError: If the request fails
+        """
+        self._validate_org_id(org_id)
+        self._validate_template_id(template_id)
+        self._validate_step_id(step_id)
+        self._validate_field_id(field_id)
+        
+        try:
+            # Format options for API
+            formatted_options = []
+            for i, option in enumerate(options):
+                if isinstance(option, str):
+                    formatted_options.append({
+                        'value': option.lower().replace(' ', '_'),
+                        'label': option,
+                        'position': i + 1
+                    })
+                elif isinstance(option, dict):
+                    formatted_options.append(option)
+                else:
+                    formatted_options.append({
+                        'value': str(option),
+                        'label': str(option),
+                        'position': i + 1
+                    })
+            
+            # Update the field with new options using CRUD operations
+            # We need to import FormFieldCRUD here to avoid circular imports
+            from .crud_operations import FormFieldCRUD
+            crud = FormFieldCRUD(self.sdk)
+            
+            updated_capture = crud.update_form_field(
+                org_id, template_id, step_id, field_id,
+                options=formatted_options
+            )
+            
+            return updated_capture is not None
+                
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "update dropdown options", org_id=org_id, template_id=template_id, step_id=step_id, field_id=field_id)
+
+    def add_dropdown_option(self, org_id: str, template_id: str, step_id: str, field_id: str, new_option: str, position: Optional[int] = None) -> bool:
+        """
+        Add a single new option to an existing dropdown field.
+        
+        Args:
+            org_id: Organization ID
+            template_id: Template ID
+            step_id: Step ID
+            field_id: Form field ID
+            new_option: New option to add
+            position: Position to insert the option (None = append to end)
+            
+        Returns:
+            True if addition was successful
+            
+        Raises:
+            TallyfyError: If the request fails
+        """
+        try:
+            # Get current options
+            current_options = self.get_dropdown_options(org_id, template_id, step_id, field_id)
+            
+            # Add new option at specified position or end
+            if position is not None and 0 <= position <= len(current_options):
+                current_options.insert(position, new_option)
+            else:
+                current_options.append(new_option)
+            
+            # Update with new options list
+            return self.update_dropdown_options(org_id, template_id, step_id, field_id, current_options)
+            
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "add dropdown option", org_id=org_id, template_id=template_id, step_id=step_id, field_id=field_id)
+
+    def remove_dropdown_option(self, org_id: str, template_id: str, step_id: str, field_id: str, option_to_remove: str) -> bool:
+        """
+        Remove a specific option from a dropdown field.
+        
+        Args:
+            org_id: Organization ID
+            template_id: Template ID
+            step_id: Step ID
+            field_id: Form field ID
+            option_to_remove: Option to remove
+            
+        Returns:
+            True if removal was successful
+            
+        Raises:
+            TallyfyError: If the request fails
+        """
+        try:
+            # Get current options
+            current_options = self.get_dropdown_options(org_id, template_id, step_id, field_id)
+            
+            # Remove the specified option if it exists
+            if option_to_remove in current_options:
+                current_options.remove(option_to_remove)
+                
+                # Update with modified options list
+                return self.update_dropdown_options(org_id, template_id, step_id, field_id, current_options)
+            else:
+                self.sdk.logger.warning(f"Option '{option_to_remove}' not found in dropdown field {field_id}")
+                return False
+            
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "remove dropdown option", org_id=org_id, template_id=template_id, step_id=step_id, field_id=field_id)
+
+    def reorder_dropdown_options(self, org_id: str, template_id: str, step_id: str, field_id: str, ordered_options: List[str]) -> bool:
+        """
+        Reorder dropdown options to match the provided list.
+        
+        Args:
+            org_id: Organization ID
+            template_id: Template ID
+            step_id: Step ID
+            field_id: Form field ID
+            ordered_options: List of options in desired order
+            
+        Returns:
+            True if reordering was successful
+            
+        Raises:
+            TallyfyError: If the request fails
+        """
+        try:
+            # Get current options to validate
+            current_options = self.get_dropdown_options(org_id, template_id, step_id, field_id)
+            
+            # Validate that all provided options exist in current options
+            missing_options = set(ordered_options) - set(current_options)
+            if missing_options:
+                raise ValueError(f"Cannot reorder: options not found in field: {missing_options}")
+            
+            # Update with reordered options
+            return self.update_dropdown_options(org_id, template_id, step_id, field_id, ordered_options)
+            
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "reorder dropdown options", org_id=org_id, template_id=template_id, step_id=step_id, field_id=field_id)