brynq-sdk-alight 1.0.0__py3-none-any.whl

brynq_sdk_alight/address.py

@@ -0,0 +1,72 @@
+from typing import Any, Dict, Optional
+
+from .schemas import Address as AddressModel
+
+
+class Address:
+    """
+    High-level Address API. Address changes are updates to IndicativeData.
+
+    Usage:
+        alight = Alight()
+        xml = alight.address.update(
+            data={...},
+            person_id="35561",
+            employee_id="35561ZZGB",
+        )
+    """
+
+    def __init__(self, client: Any):
+        self._client = client
+
+    def update(
+        self,
+        data: Dict[str, Any],
+        *,
+        person_id: str,
+        employee_id: str,
+        logical_id: Optional[str] = None,
+        envelope_options: Optional[Dict[str, Any]] = None,
+        employee_data: Optional[Dict[str, Any]] = None,
+        pretty_print: bool = True,
+    ) -> str:
+        """
+        Update address (actionCode=CHANGE). Returns XML string.
+        Requires both person_id and employee_id per integration constraints.
+
+        Example:
+            >>> alight.address.update(
+            ...     data={
+            ...         "address_line_1": "10 Downing Street",
+            ...         "town": "London",
+            ...         "postal_code": "SW1A 2AA",
+            ...         "address_valid_from": "2024-01-01",
+            ...     },
+            ...     person_id="35561",
+            ...     employee_id="35561ZZGB",
+            ... )
+        """
+        payload: dict[str, Any] = {
+            "person_id": person_id,
+            "employee_id": employee_id,
+        }
+
+        # build from flat fields
+        address_model = AddressModel(**data)
+        payload["address"] = address_model.model_dump(exclude_none=True, by_alias=True)
+
+        if "address_valid_from" in data:
+            payload["address_valid_from"] = data["address_valid_from"]
+        if "address_valid_to" in data:
+            payload["address_valid_to"] = data["address_valid_to"]
+
+        if employee_data:
+            payload.update(employee_data)
+
+        return self._client.generate_employee_xml(
+            employee=payload,
+            action_code="CHANGE",
+            logical_id=logical_id,
+            envelope_options=envelope_options,
+            pretty_print=pretty_print,
+        )

brynq_sdk_alight/archive/flat_wrapper.py

@@ -0,0 +1,139 @@
+"""
+Flat wrapper for XSD schemas.
+Provides a simple interface that automatically maps flat dictionaries to complex XSD schemas.
+"""
+
+from typing import Any, Dict, Optional, Type, get_origin, get_args
+from pydantic import BaseModel
+from xsdata.models.datatype import XmlDate
+from xsdata_pydantic.bindings import XmlSerializer
+
+
+class SchemaWrapper:
+    """
+    Generic wrapper for any XSD schema.
+    Converts flat dictionaries to proper XSD format without field duplication.
+    
+    Usage:
+        employee_data = {
+            "person_id": "12345",
+            "given_name": "John",
+            "family_name": "Smith",
+            "birth_date": "1990-01-01",
+            # ... any other fields matching the schema
+        }
+        
+        # Create wrapper with the flat data and schema class
+        wrapper = SchemaWrapper(employee_data, IndicativeDataType)
+        
+        # Get XML directly
+        xml = wrapper.to_xml()
+    """
+    
+    def __init__(self, data: Dict[str, Any], schema_class: Type[BaseModel]):
+        """
+        Initialize with flat data and target schema class.
+        
+        Args:
+            data: Flat dictionary with field names matching schema fields
+            schema_class: XSD-generated schema class to use (e.g. IndicativeDataType)
+        """
+        self.data = data
+        self.schema_class = schema_class
+    
+    def _xsd_flat_to_nested(self, flat_dict: Dict[str, Any], model: Type[BaseModel]) -> Dict[str, Any]:
+        """
+        Convert flat dictionary to nested structure using schema introspection.
+        Uses the model's field types to determine how to structure the data.
+        """
+        nested = {}
+        
+        for name, field in model.model_fields.items():
+            key_in_input = name  # Original model field name as key in flat_dict
+            alias = field.alias or name
+            
+            # Handle nested BaseModel fields (recursively) 
+            if isinstance(field.annotation, type) and issubclass(field.annotation, BaseModel):
+                nested[alias] = self._xsd_flat_to_nested(flat_dict, field.annotation)
+            
+            # Handle Union types with BaseModel (like Optional[SomeModel])
+            elif any(isinstance(item, type) and issubclass(item, BaseModel) 
+                    for item in get_args(field.annotation) if isinstance(item, type)):
+                # Get the BaseModel class from the Union
+                nested_model = next((item for item in get_args(field.annotation) 
+                                   if isinstance(item, type) and issubclass(item, BaseModel)), None)
+                if nested_model:
+                    nested[alias] = self._xsd_flat_to_nested(flat_dict, nested_model)
+            
+            # Handle primitive fields - PURE schema introspection, NO hardcoding!
+            else:
+                if key_in_input in flat_dict:
+                    value = flat_dict[key_in_input]
+                    
+                    # XSD enhancement: Check if this field type needs {"value": ...} wrapping
+                    field_type = self._unwrap_optional_and_list(field.annotation)
+                    if (hasattr(field_type, 'model_fields') and
+                        'value' in getattr(field_type, 'model_fields', {})):
+                        # Automatic XmlDate conversion for date fields (minimal logic)
+                        if 'date' in key_in_input.lower() and isinstance(value, str):
+                            nested[alias] = {"value": XmlDate.from_string(value)}
+                        else:
+                            nested[alias] = {"value": value}
+                    else:
+                        nested[alias] = value
+        
+        return nested
+    
+    def _unwrap_optional_and_list(self, field_type):
+        """Helper to unwrap Optional and List types to get the core type."""
+        # Handle Optional[T] (Union[T, None])
+        origin = get_origin(field_type)
+        if origin is type(None) or str(origin) == 'typing.Union':
+            args = get_args(field_type)
+            if args:
+                for arg in args:
+                    if arg is not type(None):
+                        field_type = arg
+                        break
+        
+        # Handle List[T]
+        if get_origin(field_type) is list:
+            args = get_args(field_type)
+            if args:
+                field_type = args[0]
+        
+        return field_type
+    
+    def to_nested_dict(self) -> Dict[str, Any]:
+        """Convert flat data to nested dictionary structure using schema introspection."""
+        return self._xsd_flat_to_nested(self.data, self.schema_class)
+    
+    def to_model(self) -> BaseModel:
+        """Convert flat data to proper schema model instance using introspection."""
+        nested_data = self._xsd_flat_to_nested(self.data, self.schema_class)
+        return self.schema_class.model_validate(nested_data)
+    
+    def to_xml(self, pretty_print: bool = True) -> str:
+        """
+        Generate XML output directly from flat data.
+        
+        Args:
+            pretty_print: Whether to format the XML with proper indentation
+            
+        Returns:
+            XML string representation of the data
+        """
+        from xml.dom import minidom
+        
+        model = self.to_model()
+        serializer = XmlSerializer()
+        xml_output = serializer.render(model)
+        
+        # Optional pretty printing
+        if pretty_print:
+            dom = minidom.parseString(xml_output)
+            xml_output = dom.toprettyxml(indent="  ")
+            xml_output = '\n'.join([line for line in xml_output.split('\n') if line.strip()])
+        
+        return xml_output
+

brynq_sdk_alight/archive/hrxml_generator.py

@@ -0,0 +1,280 @@
+"""
+HR-XML Generator for Alight Integration
+
+This module provides functions to generate HR-XML documents using XSData models
+with proper Alight envelope structure and namespace handling.
+"""
+
+import uuid
+from datetime import datetime
+from typing import Optional, Dict, Any
+from xml.dom import minidom
+
+from xsdata.models.datatype import XmlDate, XmlDateTime
+from xsdata_pydantic.bindings import XmlSerializer as PydanticXmlSerializer
+
+from .schemas.hrxml_indicative_data import IndicativeDataType, IndicativeData
+from .schemas.flattened_main_schemas.process_pay_serv_emp import (
+    ProcessPayServEmp, DataArea, PayServEmp, PayServEmpExtension, PayServEmpPayElements
+)
+from .schemas.openapplications_bod import ApplicationArea, Sender
+
+
+def create_hrxml_from_data(person_data: Dict[str, Any]) -> IndicativeDataType:
+    """
+    Create HR-XML IndicativeDataType from person data dictionary.
+    
+    Args:
+        person_data: Dictionary containing person, employee, employment, deployment, and remuneration data
+        
+    Returns:
+        IndicativeDataType: Validated XSData model instance
+    """
+    try:
+        indicative_data = IndicativeDataType.model_validate(person_data)
+        return indicative_data
+    except Exception as e:
+        raise ValueError(f"Failed to create HR-XML from data: {e}")
+
+
+def create_extension_from_data(extension_data: Dict[str, Any]) -> PayServEmpExtension:
+    """
+    Create PayServEmpExtension from extension data dictionary.
+    
+    Args:
+        extension_data: Dictionary containing payment instructions, cost assignments, etc.
+        
+    Returns:
+        PayServEmpExtension: Validated XSData model instance
+    """
+    try:
+        extension = PayServEmpExtension.model_validate(extension_data)
+        return extension
+    except Exception as e:
+        raise ValueError(f"Failed to create extension from data: {e}")
+
+
+def create_pay_elements_from_data(pay_elements_data: Dict[str, Any]) -> PayServEmpPayElements:
+    """
+    Create PayServEmpPayElements from pay elements data dictionary.
+    
+    Args:
+        pay_elements_data: Dictionary containing pay elements
+        
+    Returns:
+        PayServEmpPayElements: Validated XSData model instance
+    """
+    try:
+        pay_elements = PayServEmpPayElements.model_validate(pay_elements_data)
+        return pay_elements
+    except Exception as e:
+        raise ValueError(f"Failed to create pay elements from data: {e}")
+
+
+def create_complete_alight_envelope(
+    indicative_data: IndicativeDataType,
+    extension: Optional[PayServEmpExtension] = None,
+    pay_elements: Optional[PayServEmpPayElements] = None,
+    action_code: str = "ADD",
+    logical_id: str = "TST-GB003-1001",
+    language_code: str = "en-US",
+    system_environment_code: str = "TST NF",
+    release_id: str = "DEFAULT"
+) -> ProcessPayServEmp:
+    """
+    Create the complete Alight XML envelope using XSData models.
+    
+    Args:
+        indicative_data: The HR-XML indicative data
+        extension: Optional Alight-specific extensions
+        pay_elements: Optional pay elements
+        action_code: Action code for the process (default: "ADD")
+        logical_id: Logical ID for the sender (default: "TST-GB003-1001")
+        language_code: Language code (default: "en-US")
+        system_environment_code: System environment (default: "TST NF")
+        release_id: Release ID (default: "DEFAULT")
+        
+    Returns:
+        ProcessPayServEmp: Complete envelope ready for serialization
+    """
+    # Create timestamp and BODID
+    timestamp = datetime.now()
+    bod_id = str(uuid.uuid4()).upper()
+
+    try:
+        # Create Sender
+        sender_data = {
+            "logical_id": {"value": logical_id},
+            "component_id": {"value": "PAYROLL"},
+            "reference_id": {"value": "hrisxml"},
+            "confirmation_code": {"value": "Always"}
+        }
+        sender = Sender.model_validate(sender_data)
+
+        # Create ApplicationArea
+        app_area_data = {
+            "sender": sender,
+            "creation_date_time": {"value": XmlDateTime.from_datetime(timestamp)},
+            "bodid": {"value": bod_id}
+        }
+        application_area = ApplicationArea.model_validate(app_area_data)
+
+        # Create PayServEmp (contains our IndicativeData + Extensions)
+        # Need to create IndicativeData wrapper (not IndicativeDataType)
+        indicative_data_wrapper = IndicativeData(
+            indicative_person_dossier=indicative_data.indicative_person_dossier
+        )
+
+        pay_serv_emp_data = {
+            "indicative_data": indicative_data_wrapper
+        }
+        
+        # Add optional components if provided
+        if extension:
+            pay_serv_emp_data["pay_serv_emp_extension"] = extension
+        if pay_elements:
+            pay_serv_emp_data["pay_serv_emp_pay_elements"] = pay_elements
+            
+        pay_serv_emp = PayServEmp.model_validate(pay_serv_emp_data)
+
+        # Create Process with ActionExpression
+        process_data = {
+            "action_criteria": [{
+                "action_expression": [{
+                    "action_code": action_code
+                }]
+            }]
+        }
+
+        # Create DataArea
+        data_area_data = {
+            "process": process_data,
+            "pay_serv_emp": [pay_serv_emp]
+        }
+        data_area = DataArea.model_validate(data_area_data)
+
+        # Create the complete ProcessPayServEmp envelope
+        envelope_data = {
+            "application_area": application_area,
+            "data_area": data_area,
+            "language_code": language_code,
+            "system_environment_code": system_environment_code,
+            "release_id": release_id
+        }
+
+        complete_envelope = ProcessPayServEmp.model_validate(envelope_data)
+        return complete_envelope
+
+    except Exception as e:
+        raise ValueError(f"Failed to create complete Alight envelope: {e}")
+
+
+def serialize_with_namespaces(
+    envelope: ProcessPayServEmp,
+    pretty_print: bool = True,
+    custom_namespaces: Optional[Dict[str, str]] = None
+) -> str:
+    """
+    Serialize ProcessPayServEmp envelope to XML with proper namespace handling.
+    
+    Args:
+        envelope: The ProcessPayServEmp envelope to serialize
+        pretty_print: Whether to format the XML with indentation (default: True)
+        custom_namespaces: Custom namespace mappings (prefix -> namespace URI)
+        
+    Returns:
+        str: Serialized XML string
+    """
+    # Default namespace mappings for Alight standard prefixes
+    namespace_map = custom_namespaces or {
+        "nga": "http://www.ngahr.com/ngapexxml/1",
+        "oa": "http://www.openapplications.org/oagis/9", 
+        "hr": "http://www.hr-xml.org/3"
+    }
+    
+    try:
+        # Use ns_map parameter for clean namespace mapping
+        pydantic_serializer = PydanticXmlSerializer()
+        raw_xml = pydantic_serializer.render(envelope, ns_map=namespace_map)
+        
+        if pretty_print:
+            # Pretty print the XML
+            dom = minidom.parseString(raw_xml)
+            pretty_xml = dom.toprettyxml(indent="  ", encoding=None)
+            
+            # Clean up extra blank lines
+            lines = [line for line in pretty_xml.split('\n') if line.strip()]
+            return '\n'.join(lines)
+        else:
+            return raw_xml
+            
+    except Exception as e:
+        # Fallback without ns_map if it fails
+        try:
+            pydantic_serializer = PydanticXmlSerializer()
+            raw_xml = pydantic_serializer.render(envelope)
+            
+            if pretty_print:
+                dom = minidom.parseString(raw_xml)
+                pretty_xml = dom.toprettyxml(indent="  ", encoding=None)
+                lines = [line for line in pretty_xml.split('\n') if line.strip()]
+                return '\n'.join(lines)
+            else:
+                return raw_xml
+                
+        except Exception as e2:
+            raise ValueError(f"Failed to serialize envelope: {e2}")
+
+
+def generate_complete_hrxml(
+    person_data: Dict[str, Any],
+    extension_data: Optional[Dict[str, Any]] = None,
+    pay_elements_data: Optional[Dict[str, Any]] = None,
+    action_code: str = "ADD",
+    logical_id: str = "TST-GB003-1001",
+    pretty_print: bool = True
+) -> str:
+    """
+    High-level function to generate complete Alight HR-XML from data dictionaries.
+    
+    Args:
+        person_data: Dictionary containing person/employee/employment data
+        extension_data: Optional dictionary containing Alight extensions
+        pay_elements_data: Optional dictionary containing pay elements
+        action_code: Action code for the process (default: "ADD")
+        logical_id: Logical ID for the sender (default: "TST-GB003-1001")
+        pretty_print: Whether to format the XML with indentation (default: True)
+        
+    Returns:
+        str: Complete Alight HR-XML string
+    """
+    try:
+        # Create HR-XML content
+        indicative_data = create_hrxml_from_data(person_data)
+        
+        # Create optional components
+        extension = None
+        pay_elements = None
+        
+        if extension_data:
+            extension = create_extension_from_data(extension_data)
+            
+        if pay_elements_data:
+            pay_elements = create_pay_elements_from_data(pay_elements_data)
+        
+        # Create complete envelope
+        envelope = create_complete_alight_envelope(
+            indicative_data=indicative_data,
+            extension=extension,
+            pay_elements=pay_elements,
+            action_code=action_code,
+            logical_id=logical_id
+        )
+        
+        # Serialize to XML
+        xml_string = serialize_with_namespaces(envelope, pretty_print=pretty_print)
+        
+        return xml_string
+        
+    except Exception as e:
+        raise ValueError(f"Failed to generate complete HR-XML: {e}") 

brynq_sdk_alight/archive/managers.py

@@ -0,0 +1,132 @@
+"""
+Fully generic manager for the Alight SDK.
+Pure XSD schema-driven transformations - zero hardcoded mappings.
+"""
+
+from typing import Dict, Any, Optional, TYPE_CHECKING, List, get_origin, get_args
+from pydantic import BaseModel
+
+from .schemas.hrxml_indicative_data import IndicativeDataType
+
+if TYPE_CHECKING:
+    from . import Alight
+
+
+class EmployeeManager:
+    """Fully generic employee manager - pure XSD schema-driven conversion."""
+
+    def __init__(self, alight_sdk: 'Alight'):
+        self.alight_sdk = alight_sdk
+
+    def create_newhire_simple(self, flat_data: Dict[str, Any],
+                             logical_id: Optional[str] = None,
+                             pretty_print: bool = True,
+                             save_to_file: bool = False,
+                             filename: Optional[str] = None) -> str:
+        """
+        Create NewHire XML from flat dictionary using pure XSD schema conversion.
+        """
+        nested_data = self._flat_to_nested(flat_data)
+        return self.alight_sdk.generate_newhire_xml(
+            person_data=nested_data,
+            logical_id=logical_id,
+            pretty_print=pretty_print
+        )
+
+    def create_employee_change_simple(self, flat_data: Dict[str, Any],
+                                     logical_id: Optional[str] = None,
+                                     pretty_print: bool = True,
+                                     save_to_file: bool = False,
+                                     filename: Optional[str] = None) -> str:
+        """
+        Create Employee Change XML from flat dictionary using pure XSD schema conversion.
+        """
+        nested_data = self._flat_to_nested(flat_data)
+        return self.alight_sdk.generate_employee_change_xml(
+            person_data=nested_data,
+            logical_id=logical_id,
+            pretty_print=pretty_print
+        )
+
+    def _flat_to_nested(self, flat_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Convert flat data to nested using PURE XSD schema inspection.
+        Zero hardcoded mappings - everything is generic and schema-driven.
+        """
+        # Check if data is already in schema-compliant format (has proper nesting)
+        if self._is_already_schema_compliant(flat_data):
+            if self.alight_sdk.debug:
+                print("✅ Data is already schema-compliant, using directly")
+            return flat_data
+        
+        # Use the generic XSD-aware conversion for truly flat data
+        return self._xsd_flat_to_nested(flat_data, IndicativeDataType)
+    
+    def _is_already_schema_compliant(self, data: Dict[str, Any]) -> bool:
+        """Check if data is already in schema-compliant format."""
+        # Look for key indicators that it's already structured correctly
+        if "indicative_person_dossier" in data:
+            person_dossier = data["indicative_person_dossier"]
+            # Check if main sections are lists (as required by schema)
+            if (isinstance(person_dossier.get("indicative_person"), list) and
+                isinstance(person_dossier.get("indicative_employee"), list) and
+                isinstance(person_dossier.get("indicative_employment"), list)):
+                return True
+        return False
+
+    def _xsd_flat_to_nested(self, flat_dict: Dict[str, Any], model: BaseModel) -> Dict[str, Any]:
+        """
+        Generic XSD-aware version exactly like your Functions.flat_dict_to_nested_dict.
+        Recursively processes the schema and handles XSD {"value": ...} format automatically.
+        """
+        nested = {}
+
+        for name, field in model.model_fields.items():
+            key_in_input = name  # Original model field name as key in flat_dict
+            alias = field.alias or name
+
+            # Handle nested BaseModel fields (recursively) - exact same logic as your function
+            if isinstance(field.annotation, type) and issubclass(field.annotation, BaseModel):
+                nested[alias] = self._xsd_flat_to_nested(flat_dict, field.annotation)
+
+            # Handle Union types with BaseModel (like Optional[SomeModel]) - exact same logic
+            elif any(isinstance(item, type) and issubclass(item, BaseModel) for item in get_args(field.annotation)):
+                # Get the BaseModel class from the Union
+                nested_model = next(item for item in get_args(field.annotation)
+                                   if isinstance(item, type) and issubclass(item, BaseModel))
+                nested[alias] = self._xsd_flat_to_nested(flat_dict, nested_model)
+
+            # Handle primitive fields - your logic + XSD value wrapping
+            else:
+                if key_in_input in flat_dict:
+                    value = flat_dict[key_in_input]
+
+                    # XSD enhancement: Check if this field type needs {"value": ...} wrapping
+                    field_type = self._unwrap_optional_and_list(field.annotation)
+                    if (hasattr(field_type, 'model_fields') and
+                        'value' in getattr(field_type, 'model_fields', {})):
+                        nested[alias] = {"value": value}
+                    else:
+                        nested[alias] = value
+
+        return nested
+
+    def _unwrap_optional_and_list(self, field_type):
+        """Helper to unwrap Optional and List types to get the core type."""
+        # Handle Optional[T] (Union[T, None])
+        origin = get_origin(field_type)
+        if origin is type(Optional[str]) or str(origin) == 'typing.Union':
+            args = get_args(field_type)
+            if args:
+                for arg in args:
+                    if arg is not type(None):
+                        field_type = arg
+                        break
+
+        # Handle List[T]
+        if get_origin(field_type) is list:
+            args = get_args(field_type)
+            if args:
+                field_type = args[0]
+
+        return field_type