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

brynq_sdk_alight/employee.py

@@ -0,0 +1,81 @@
+from typing import Any, Dict, Optional
+
+
+class Employee:
+    """
+    High-level Employee API (no manager layer).
+
+    Usage:
+        alight = Alight()
+        xml = alight.employee.create({...})
+        xml = alight.employee.update(EmployeeModel(...))
+    """
+
+    def __init__(self, client: Any):
+        self._client = client
+
+    def create(
+        self,
+        data: Dict[str, Any],
+        *,
+        logical_id: Optional[str] = None,
+        extension_data: Optional[Dict[str, Any]] = None,
+        pay_elements_data: Optional[Dict[str, Any]] = None,
+        envelope_options: Optional[Dict[str, Any]] = None,
+        pretty_print: bool = True,
+    ) -> str:
+        """
+        Create a New Hire XML document (actionCode=ADD).
+        Returns XML string.
+
+        Example:
+            >>> alight.employee.create(
+            ...     {
+            ...         "person_id": "35561",
+            ...         "employee_id": "35561ZZGB",
+            ...         "given_name": "Alex",
+            ...         "family_name": "Mason",
+            ...     },
+            ...     extension_data={"bank_accounts": [{"iban": "GB00BARC20201530093459"}]},
+            ... )
+        """
+        return self._client.generate_employee_xml(
+            employee=data,
+            action_code="ADD",
+            logical_id=logical_id,
+            extension_data=extension_data,
+            pay_elements_data=pay_elements_data,
+            envelope_options=envelope_options,
+            pretty_print=pretty_print,
+        )
+
+    def update(
+        self,
+        data: Dict[str, Any],
+        *,
+        logical_id: Optional[str] = None,
+        extension_data: Optional[Dict[str, Any]] = None,
+        pay_elements_data: Optional[Dict[str, Any]] = None,
+        envelope_options: Optional[Dict[str, Any]] = None,
+        pretty_print: bool = True,
+    ) -> str:
+        """
+        Create an Employee Change XML document (actionCode=CHANGE).
+        Returns XML string.
+
+        Example:
+            >>> alight.employee.update(
+            ...     {"person_id": "35561", "employee_id": "35561ZZGB", "email": "alex@example.com"},
+            ...     extension_data={"bank_accounts": [{"iban": "GB00BARC20201530093459"}]},
+            ...     pay_elements_data={"pay_element": [{"id": [{"value": "0010"}], "amount": {"value": "45000"}}]},
+            ... )
+        """
+        return self._client.generate_employee_xml(
+            employee=data,
+            action_code="CHANGE",
+            logical_id=logical_id,
+            extension_data=extension_data,
+            pay_elements_data=pay_elements_data,
+            envelope_options=envelope_options,
+            pretty_print=pretty_print,
+        )

brynq_sdk_alight/job.py

@@ -0,0 +1,89 @@
+from typing import Any, Dict, Optional, Mapping
+
+from .schemas import Job as JobModel
+
+
+class Job:
+    """
+    High-level Job/Deployment API.
+
+    Usage:
+        alight = Alight()
+        xml = alight.job.create(data={...}, person_id="35561", employee_id="35561ZZGB")
+        xml = alight.job.update(data={...}, person_id="35561", employee_id="35561ZZGB")
+    """
+
+    def __init__(self, client: Any):
+        self._client = client
+
+    def create(
+        self,
+        data: Dict[str, Any],
+        *,
+        person_id: str,
+        employee_id: str,
+        logical_id: Optional[str] = None,
+        envelope_options: Optional[Dict[str, Any]] = None,
+        pretty_print: bool = True,
+    ) -> str:
+        """
+        Create job/deployment data (actionCode=ADD). Returns XML string.
+        Requires both person_id and employee_id.
+
+        Example:
+            >>> alight.job.create(
+            ...     data={"job_code": "FIN-MGR", "department": "Finance"},
+            ...     person_id="35561",
+            ...     employee_id="35561ZZGB",
+            ... )
+        """
+        job_model = JobModel(**data)
+        payload = {
+            "person_id": person_id,
+            "employee_id": employee_id,
+            "job": job_model.model_dump(exclude_none=True, by_alias=True),
+        }
+
+        return self._client.generate_employee_xml(
+            employee=payload,
+            action_code="ADD",
+            logical_id=logical_id,
+            envelope_options=envelope_options,
+            pretty_print=pretty_print,
+        )
+
+    def update(
+        self,
+        data: Mapping[str, Any],
+        *,
+        person_id: str,
+        employee_id: str,
+        logical_id: Optional[str] = None,
+        envelope_options: Optional[dict[str, Any]] = None,
+        pretty_print: bool = True,
+    ) -> str:
+        """
+        Update job/deployment data (actionCode=CHANGE). Returns XML string.
+        Requires both person_id and employee_id.
+
+        Example:
+            >>> alight.job.update(
+            ...     data={"job": {"job_code": "FIN-DIR", "effective_date": "2024-04-01"}},
+            ...     person_id="35561",
+            ...     employee_id="35561ZZGB",
+            ... )
+        """
+        job_model = JobModel(**dict(data))
+        payload = {
+            "person_id": person_id,
+            "employee_id": employee_id,
+            "job": job_model.model_dump(exclude_none=True, by_alias=True),
+        }
+
+        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/leave.py

@@ -0,0 +1,97 @@
+from typing import Any, Dict, Optional
+
+from .schemas import Leave as LeaveModel
+
+
+class Leave:
+    """
+    High-level Leave API.
+
+    Usage:
+        alight = Alight()
+        xml = alight.leave.create(data={...}, person_id="35561", employee_id="35561ZZGB")
+        xml = alight.leave.update(data={...}, person_id="35561", employee_id="35561ZZGB")
+    """
+
+    def __init__(self, client: Any):
+        self._client = client
+
+    def create(
+        self,
+        data: Dict[str, Any],
+        *,
+        person_id: str,
+        employee_id: str,
+        logical_id: Optional[str] = None,
+        envelope_options: Optional[Dict[str, Any]] = None,
+        pretty_print: bool = True,
+    ) -> str:
+        """
+        Create leave entry (actionCode=ADD). Returns XML string.
+        Requires both person_id and employee_id.
+
+        Example:
+            >>> alight.leave.create(
+            ...     data={
+            ...         "leave_type": "PARENTAL",
+            ...         "start_date": "2024-02-01",
+            ...         "end_date": "2024-02-15",
+            ...     },
+            ...     person_id="35561",
+            ...     employee_id="35561ZZGB",
+            ... )
+        """
+        leave_model = LeaveModel(**data)
+        payload = {
+            "person_id": person_id,
+            "employee_id": employee_id,
+            "leave": leave_model.model_dump(exclude_none=True, by_alias=True),
+        }
+
+        return self._client.generate_employee_xml(
+            employee=payload,
+            action_code="ADD",
+            logical_id=logical_id,
+            envelope_options=envelope_options,
+            pretty_print=pretty_print,
+        )
+
+    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,
+        pretty_print: bool = True,
+    ) -> str:
+        """
+        Update leave entry (actionCode=CHANGE). Returns XML string.
+        Requires both person_id and employee_id.
+
+        Example:
+            >>> alight.leave.update(
+            ...     data={"leave": {"leave_type": "SICK", "status": "Cancelled"}},
+            ...     person_id="35561",
+            ...     employee_id="35561ZZGB",
+            ... )
+        """
+        if 'leave' in data and data['leave'] is not None:
+            nested = data['leave']
+            leave_model = nested if isinstance(nested, LeaveModel) else LeaveModel(**nested)
+        else:
+            leave_model = LeaveModel(**data)
+        payload = {
+            "person_id": person_id,
+            "employee_id": employee_id,
+            "leave": leave_model.model_dump(exclude_none=True, by_alias=True),
+        }
+
+        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/pay_elements.py

@@ -0,0 +1,97 @@
+from typing import Any, Dict, List, Optional
+
+from .schemas.payments import PayElementCreate
+from .schemas.generated_envelope_xsd_schema.process_pay_serv_emp import (
+    PayServEmpPayElements as XsdPayServEmpPayElements,
+)
+
+
+class PayElements:
+    """
+    High-level PayElements API. Builds PayServEmpPayElements from a list of PayElementCreate.
+
+    Usage:
+        alight = Alight()
+        xml = alight.pay_elements.create(elements=[{...}], person_id="35561", employee_id="35561ZZGB")
+        xml = alight.pay_elements.update(elements=[{...}], person_id="35561", employee_id="35561ZZGB")
+    """
+
+    def __init__(self, client: Any):
+        self._client = client
+
+    def _build_pay_elements(self, elements: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """
+        Normalize incoming pay elements and validate them against the generated XSD model.
+
+        Accepts plain dictionaries and returns the nested payload expected by `generate_employee_xml`.
+
+        Example:
+            >>> self._build_pay_elements([
+            ...     {"element_code": "0010", "amount": 1200, "currency_code": "GBP"},
+            ... ])
+        """
+        normalized: List[Dict[str, Any]] = []
+        for item in elements:
+            model = item if isinstance(item, PayElementCreate) else PayElementCreate(**item)
+            normalized.append(model.to_nested_dict())
+        payload = {"pay_element": normalized}
+        XsdPayServEmpPayElements.model_validate(payload)
+        return payload
+
+    def create(
+        self,
+        *,
+        elements: List[Dict[str, Any]],
+        person_id: str,
+        employee_id: str,
+        logical_id: Optional[str] = None,
+        envelope_options: Optional[Dict[str, Any]] = None,
+        pretty_print: bool = True,
+    ) -> str:
+        """
+        Generate an ADD envelope for pay elements using the minimal person identifiers.
+
+        Example:
+            >>> alight.pay_elements.create(
+            ...     elements=[{"element_code": "0010", "amount": "1200", "currency_code": "GBP"}],
+            ...     person_id="35561",
+            ...     employee_id="35561ZZGB",
+            ... )
+        """
+        pay_elements_data = self._build_pay_elements(elements)
+
+        return self._client.generate_employee_xml(
+            employee={"person_id": person_id, "employee_id": employee_id},
+            action_code="ADD",
+            logical_id=logical_id,
+            pay_elements_data=pay_elements_data,
+            envelope_options=envelope_options,
+            pretty_print=pretty_print,
+        )
+
+    def update(
+        self,
+        *,
+        elements: List[Dict[str, Any]],
+        person_id: str,
+        employee_id: str,
+        logical_id: Optional[str] = None,
+        envelope_options: Optional[Dict[str, Any]] = None,
+        pretty_print: bool = True,
+    ) -> str:
+        """
+        Generate a CHANGE envelope for existing pay elements while keeping identifiers flat.
+
+        Mirrors `create` but reuses the CHANGE action code so downstream consumers can differ updates
+        from new allocations without rebuilding envelopes manually.
+        """
+        pay_elements_data = self._build_pay_elements(elements)
+
+        return self._client.generate_employee_xml(
+            employee={"person_id": person_id, "employee_id": employee_id},
+            action_code="CHANGE",
+            logical_id=logical_id,
+            pay_elements_data=pay_elements_data,
+            envelope_options=envelope_options,
+            pretty_print=pretty_print,
+        )

brynq_sdk_alight/salary.py

@@ -0,0 +1,89 @@
+from typing import Any, Dict, Optional, Union
+from xsdata.models.datatype import XmlDate
+
+from .schemas import Salary as SalaryModel, EmployeeCreate as EmployeeModel
+
+
+class Salary:
+    """
+    High-level Salary API (no manager layer).
+
+    Usage:
+        alight = Alight()
+        xml = alight.salary.update(salary={...}, identifiers={"person_id": "35561", "employee_id": "35561ZZGB"})
+    """
+
+    def __init__(self, client: Any):
+        self._client = client
+
+    def update(
+        self,
+        salary: Union[SalaryModel, Dict[str, Any]],
+        *,
+        identifiers: Optional[Dict[str, Any]] = None,
+        employee: Optional[Union[EmployeeModel, Dict[str, Any]]] = None,
+        logical_id: Optional[str] = None,
+        pretty_print: bool = True,
+    ) -> str:
+        """
+        Create an Employee Change XML with salary change as PayElements.
+        Returns XML string.
+
+        Example:
+            >>> alight.salary.update(
+            ...     salary={"base_salary": 42000, "currency_code": "GBP"},
+            ...     identifiers={"person_id": "35561", "employee_id": "35561ZZGB"},
+            ... )
+
+        Passing `salary` as a plain dict is enough—the helper wraps it in the generated `Salary` schema
+        and derives the recurring pay element payload automatically.
+        """
+        # Build or augment an EmployeeModel with identifiers and salary
+        if employee is None:
+            if not identifiers or "person_id" not in identifiers:
+                raise ValueError("identifiers must include at least 'person_id' when no employee is provided")
+            base: Dict[str, Any] = {
+                "person_id": identifiers.get("person_id"),
+            }
+            if identifiers.get("employee_id"):
+                base["employee_id"] = identifiers.get("employee_id")
+            employee_model = EmployeeModel(**base)
+        else:
+            employee_model = employee if isinstance(employee, EmployeeModel) else EmployeeModel(**employee)
+
+        # Normalize salary model
+        salary_model = salary if isinstance(salary, SalaryModel) else SalaryModel(**salary)
+
+        # Convert salary to alias-based nested dict compatible with to_model mapping
+        # Alight expects a default pay element code/type even if upstream sources omit them,
+        # so fall back to the recurring base salary identifiers that match standard setup.
+        pay_elements_data = {
+            "pay_element": [
+                {
+                    "id": [{"value": salary_model.element_code or "0010"}],
+                    "pay_element_type": {"value": salary_model.element_type or "RECURRING"},
+                    "amount": {"value": f"{salary_model.base_salary:.2f}"},
+                    "currency_code": {"value": salary_model.currency_code},
+                    "valid_from": (
+                        XmlDate.from_string(salary_model.valid_from.isoformat())
+                        if salary_model.valid_from
+                        else None
+                    ),
+                }
+            ]
+        }
+
+        # Clean None values in pay element
+        for k in list(pay_elements_data["pay_element"][0].keys()):
+            if pay_elements_data["pay_element"][0][k] is None:
+                del pay_elements_data["pay_element"][0][k]
+
+        # Also mirror salary on the Employee flat fields so IndicativeData contains identifiers
+        # Employee.to_model handles wrapping; pay elements go via pay_elements_data
+        return self._client.generate_employee_xml(
+            employee=employee_model,
+            action_code="CHANGE",
+            logical_id=logical_id,
+            pay_elements_data=pay_elements_data,
+            pretty_print=pretty_print,
+        )

brynq_sdk_alight/schemas/__init__.py

@@ -0,0 +1,26 @@
+"""
+Alight SDK schema models.
+"""
+
+from .employee import EmployeeCreate
+from .salary import Salary
+from .address import Address
+from .job import Job
+from .leave import Leave
+from .termination import Termination
+from .absence import Absence
+from .timequota import TimeQuota
+from .payments import PayServEmpExtensionCreate, PayElementCreate
+
+__all__ = [
+    "EmployeeCreate",
+    "Salary",
+    "Address",
+    "Job",
+    "Leave",
+    "Termination",
+    "Absence",
+    "TimeQuota",
+    "PayServEmpExtensionCreate",
+    "PayElementCreate",
+]

brynq_sdk_alight/schemas/absence.py

@@ -0,0 +1,83 @@
+"""
+Flat, user-friendly absence (time element) model for Alight SDK.
+"""
+
+import datetime
+from typing import Optional, Dict, Any, List
+from pydantic import Field, BaseModel
+
+from .utils import add_to_nested_path, convert_datetime_to_xml, post_process_nested_data
+
+
+class Absence(BaseModel):
+    """
+    Simplified time element mapping to PayServEmpTimeElements.time_element[0].
+    """
+    model_config = {
+        "populate_by_name": True
+    }
+
+    # Core identifiers and reason
+    id: Optional[str] = Field(default=None, alias="time_element[0].id[0]")
+    absence_reason: Optional[str] = Field(default=None, alias="time_element[0].absence_reason")
+
+    # Quantities
+    units: Optional[str] = Field(default=None, alias="time_element[0].units")
+    unit_type: Optional[str] = Field(default=None, alias="time_element[0].unit_type")
+
+    # Dates
+    valid_from: Optional[datetime.date] = Field(default=None, alias="time_element[0].valid_from")
+    valid_to: Optional[datetime.date] = Field(default=None, alias="time_element[0].valid_to")
+
+    # Easy additional fields
+    comments: Optional[str] = Field(default=None, alias="time_element[0].comments")
+    absence_post: Optional[str] = Field(default=None, alias="time_element[0].absence_post")
+
+    def to_nested_dict(self) -> Dict[str, Any]:
+        flat = self.model_dump(exclude_none=True, by_alias=True)
+        nested: Dict[str, Any] = {}
+        for k, v in flat.items():
+            add_to_nested_path(nested, k, v)
+        # Convert dates to XML compatible
+        for key in ("valid_from", "valid_to"):
+            if key in nested and isinstance(nested[key], (datetime.date, datetime.datetime)):
+                nested[key] = convert_datetime_to_xml(nested[key], None)
+        return nested
+
+
+class Absences(BaseModel):
+    """
+    Wrapper for multiple Absence items mapping to time_element[*].
+    """
+    absences: Optional[List[Absence]] = Field(default=None, description="List of absence time elements")
+
+    def to_nested_dict(self) -> Dict[str, Any]:
+        nested: Dict[str, Any] = {}
+        if not self.absences:
+            return nested
+        # Merge each absence into time_element list
+        time_elements: List[Dict[str, Any]] = []
+        for idx, item in enumerate(self.absences):
+            data = item.to_nested_dict()
+            # Convert indexed paths from [0] to [idx]
+            remapped: Dict[str, Any] = {}
+            for k, v in data.items():
+                remapped[k.replace("time_element[0]", f"time_element[{idx}]")] = v
+            # Build nested for this item and then merge
+            item_nested: Dict[str, Any] = {}
+            for k, v in remapped.items():
+                add_to_nested_path(item_nested, k, v)
+            # Collect the single time_element dict
+            if "time_element" in item_nested and isinstance(item_nested["time_element"], list):
+                time_elements.extend(item_nested["time_element"])
+        if time_elements:
+            nested["time_element"] = time_elements
+        # Post-process using the XSD model to wrap units and convert dates
+        try:
+            from ..schemas.generated_envelope_xsd_schema.process_pay_serv_emp import (
+                PayServEmpTimeElements as XsdPayServEmpTimeElements,
+            )
+            post_process_nested_data(nested, XsdPayServEmpTimeElements)
+        except Exception:
+            pass
+        return nested

brynq_sdk_alight/schemas/address.py

@@ -0,0 +1,113 @@
+"""
+Flat, user-friendly address model for Alight SDK.
+"""
+
+from typing import Optional, Dict, Any, List
+from pydantic import Field, BaseModel
+
+# Composition approach: plain Pydantic BaseModel; conversion handled by callers
+
+
+class Address(BaseModel):
+    """
+    Simplified address model.
+    Uses PURE schema-driven conversion - NO hardcoded structure mappings.
+    Uses aliases to match expected field names in Employee model.
+    """
+    model_config = {
+        "populate_by_name": True  # Allow populating by field name in addition to alias
+    }
+
+    line_1: str = Field(
+        description="Street address line 1",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.line_one"
+    )
+    line_2: Optional[str] = Field(
+        default=None,
+        description="Street address line 2",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.line_two"
+    )
+    line_3: Optional[str] = Field(
+        default=None,
+        description="Street address line 3",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.line_three"
+    )
+    line_4: Optional[str] = Field(
+        default=None,
+        description="Street address line 4",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.line_four"
+    )
+    line_5: Optional[str] = Field(
+        default=None,
+        description="Street address line 5",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.line_five"
+    )
+    building_number: Optional[str] = Field(
+        default=None,
+        description="Building number",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.building_number"
+    )
+    building_name: Optional[str] = Field(
+        default=None,
+        description="Building name",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.building_name"
+    )
+    street_name: Optional[str] = Field(
+        default=None,
+        description="Street name",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.street_name"
+    )
+    unit: Optional[str] = Field(
+        default=None,
+        description="Unit or apartment identifier",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.unit"
+    )
+    floor: Optional[str] = Field(
+        default=None,
+        description="Floor number",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.floor"
+    )
+    post_office_box: Optional[str] = Field(
+        default=None,
+        description="P.O. Box",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.post_office_box"
+    )
+    city: str = Field(
+        description="City name",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.city_name"
+    )
+    state_province: Optional[str] = Field(
+        default=None,
+        description="State/province",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.country_sub_division_code"
+    )
+    delivery_point_code: Optional[List[str]] = Field(
+        default=None,
+        description="Delivery point code(s)",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.delivery_point_code"
+    )
+    postal_code: str = Field(
+        description="ZIP/postal code",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.postal_code"
+    )
+    country: str = Field(
+        description="Country code (GB/US/etc.)",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.country_code"
+    )
+    city_sub_division_name: Optional[List[str]] = Field(
+        default=None,
+        description="Neighborhood or city subdivision name(s)",
+        alias="indicative_person_dossier.indicative_person.communication[2].address.city_sub_division_name"
+    )
+    use_code: Optional[str] = Field(
+        default=None,
+        description="Address use context (HOME/WORK)",
+        alias="indicative_person_dossier.indicative_person.communication[2].use_code"
+    )
+
+    def to_nested_dict(self) -> Dict[str, Any]:
+        """
+        Convert to nested structure compatible with employee address fields.
+        """
+        # Convert to dictionary with aliases - will directly map to employee fields
+        return self.model_dump(exclude_none=True, by_alias=True)