tallyfy 1.0.16__py3-none-any.whl

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)