brynq-sdk-nmbrs 2.3.4.dev0__py3-none-any.whl → 2.4.5__py3-none-any.whl

brynq_sdk_nmbrs/debtors.py

@@ -1,20 +1,36 @@
+
 import pandas as pd
 import requests
-from typing import Dict, Any
-from zeep.exceptions import Fault
+
 from brynq_sdk_functions import Functions
+
 from .department import Departments
 from .function import Functions as NmbrsFunctions
-from .schemas.debtor import DebtorsGet, DebtorCreate, DebtorUpdate
+from .schemas.debtor import DebtorsGet
 
 
 class Debtors:
+    """
+    Class for handling debtor information.
+
+    Endpoints:
+        - GET /api/debtors
+        - GET /api/debtors/info
+        - GET /api/debtors/endcontractreasons/{Year}
+    """
+
     def __init__(self, nmbrs):
         self.nmbrs = nmbrs
         self.departments = Departments(nmbrs)
         self.functions = NmbrsFunctions(nmbrs)
 
-    def get(self) -> (pd.DataFrame, pd.DataFrame):
+    def get(self) -> tuple:
+        """
+        Get a list of all debtors for the authenticated user.
+
+        Returns:
+            Tuple of (valid_data, invalid_data) DataFrames
+        """
         request = requests.Request(method='GET',
                                    url=f"{self.nmbrs.base_url}debtors")
         data = self.nmbrs.get_paginated_result(request)
@@ -25,75 +41,47 @@ class Debtors:
 
         return valid_debtors, invalid_debtors
 
-    def create(self, data: Dict[str, Any]) -> int:
+    def get_info(self) -> pd.DataFrame:
         """
-        Create a new debtor using SOAP API.
+        Get information about the authenticated debtor.
 
-        Args:
-            data: Dictionary containing debtor data with fields matching DebtorCreate schema:
-                - number: Debtor number
-                - name: Debtor name
+        Returns info about the debtor that the API keys belong to,
+        including current settings and subscription details.
 
         Returns:
-            The ID of the newly created debtor.
+            DataFrame containing debtor info
         """
-        debtor_model = DebtorCreate(**data)
-
-        if self.nmbrs.mock_mode:
-            return 12345  # Mock ID
-
-        try:
-            DebtorType = self.nmbrs.soap_client_debtors.get_type('ns0:Debtor')
-            soap_debtor = DebtorType(
-                Id=0,  # 0 for new debtor
-                Number=debtor_model.number,
-                Name=debtor_model.name
-            )
-
-            response = self.nmbrs.soap_client_debtors.service.Debtor_Insert(
-                Debtor=soap_debtor,
-                _soapheaders={'AuthHeaderWithDomain': self.nmbrs.soap_auth_header_debtors}
-            )
-            return response
-
-        except Fault as e:
-            raise Exception(f"SOAP request failed: {str(e)}")
-        except Exception as e:
-            raise Exception(f"Failed to create Debtor: {str(e)}")
-
-    def update(self, data: Dict[str, Any]):
+        resp = self.nmbrs.session.get(
+            url=f"{self.nmbrs.base_url}debtors/info",
+            timeout=self.nmbrs.timeout
+        )
+        resp.raise_for_status()
+        data = resp.json()
+
+        # Normalize the response if it's a dict
+        if isinstance(data, dict):
+            df = pd.json_normalize(data)
+        else:
+            df = pd.DataFrame(data)
+
+        return df
+
+    def get_end_contract_reasons(self, year: int) -> pd.DataFrame:
         """
-        Update a debtor using SOAP API.
+        Get the available end contract reasons for a specific year.
 
         Args:
-            data: Dictionary containing debtor data with fields matching DebtorUpdate schema:
-                - debtor_id: Debtor ID to update
-                - number: Debtor number
-                - name: Debtor name
+            year: The year to get end contract reasons for
 
         Returns:
-            Response from the API
+            DataFrame containing end contract reasons
         """
-        debtor_model = DebtorUpdate(**data)
-
-        if self.nmbrs.mock_mode:
-            return debtor_model
-
-        try:
-            DebtorType = self.nmbrs.soap_client_debtors.get_type('ns0:Debtor')
-            soap_debtor = DebtorType(
-                Id=debtor_model.debtor_id,
-                Number=debtor_model.number,
-                Name=debtor_model.name
-            )
-
-            response = self.nmbrs.soap_client_debtors.service.Debtor_Update(
-                Debtor=soap_debtor,
-                _soapheaders={'AuthHeaderWithDomain': self.nmbrs.soap_auth_header_debtors}
-            )
-            return response
-
-        except Fault as e:
-            raise Exception(f"SOAP request failed: {str(e)}")
-        except Exception as e:
-            raise Exception(f"Failed to update Debtor: {str(e)}")
+        request = requests.Request(
+            method='GET',
+            url=f"{self.nmbrs.base_url}debtors/endcontractreasons/{year}"
+        )
+
+        data = self.nmbrs.get_paginated_result(request)
+        df = pd.DataFrame(data)
+
+        return df

brynq_sdk_nmbrs/department.py

@@ -2,19 +2,13 @@ from typing import Any, Dict
 
 import pandas as pd
 import requests
-from zeep.exceptions import Fault
 
 from brynq_sdk_functions import Functions
 
 from .schemas.department import (
-    DepartmentCreate,
     DepartmentGet,
-    DepartmentMasterCreate,
-    DepartmentMasterDelete,
-    DepartmentMasterUpdate,
     EmployeeDepartmentGet,
     EmployeeDepartmentUpdate,
-    Period,
 )
 
 
@@ -119,125 +113,43 @@ class EmployeeDepartment:
 
 class Departments:
     """Master department operations (Debtor level) - uses SOAP for create/update/delete."""
-    
+
     def __init__(self, nmbrs):
         self.nmbrs = nmbrs
 
-    def get(self,
-            debtor_id: str) -> pd.DataFrame:
-        request = requests.Request(method='GET',
-                                   url=f"{self.nmbrs.base_url}debtors/{debtor_id}/departments")
-
-        data = self.nmbrs.get_paginated_result(request)
-
-        df = pd.DataFrame(data)
-        valid_departments, invalid_departments = Functions.validate_data(df=df, schema=DepartmentGet, debug=True)
-
-        return valid_departments, invalid_departments
-
-    def create(self, data: Dict[str, Any]) -> int:
+    def get(self, debtor_id: str = None) -> tuple[pd.DataFrame, pd.DataFrame]:
         """
-        Create a new master department for a debtor using SOAP API.
+        Get all departments for debtor(s).
 
         Args:
-            data: Dictionary containing department data with fields matching DepartmentMasterCreate schema:
-                - debtor_id: Debtor ID
-                - code: Department code
-                - description: Department description
+            debtor_id: Optional debtor ID. If not provided, fetches for all debtors.
 
         Returns:
-            The ID of the newly created department.
+            Tuple of (valid_departments, invalid_departments) DataFrames
         """
-        dept_model = DepartmentMasterCreate(**data)
+        if debtor_id:
+            df = self._get(debtor_id)
+        else:
+            df = pd.DataFrame()
+            for debtor in self.nmbrs.debtor_ids:
+                df = pd.concat([df, self._get(debtor)])
 
-        if self.nmbrs.mock_mode:
-            return 12345  # Mock ID
-
-        try:
-            DepartmentType = self.nmbrs.soap_client_debtors.get_type('ns0:Department')
-            soap_department = DepartmentType(
-                Id=0,  # 0 for new department
-                Code=dept_model.code,
-                Description=dept_model.description
-            )
-
-            response = self.nmbrs.soap_client_debtors.service.Department_Insert(
-                DebtorId=dept_model.debtor_id,
-                department=soap_department,
-                _soapheaders={'AuthHeaderWithDomain': self.nmbrs.soap_auth_header_debtors}
-            )
-            return response
-
-        except Fault as e:
-            raise Exception(f"SOAP request failed: {str(e)}")
-        except Exception as e:
-            raise Exception(f"Failed to create Department: {str(e)}")
-
-    def update(self, data: Dict[str, Any]):
-        """
-        Update a master department for a debtor using SOAP API.
+        if df.empty:
+            return df, pd.DataFrame()
 
-        Args:
-            data: Dictionary containing department data with fields matching DepartmentMasterUpdate schema:
-                - debtor_id: Debtor ID
-                - department_id: Department ID to update
-                - code: Department code
-                - description: Department description
+        valid_departments, invalid_departments = Functions.validate_data(df=df, schema=DepartmentGet, debug=self.nmbrs.debug)
+        return valid_departments, invalid_departments
 
-        Returns:
-            Response from the API
+    def _get(self, debtor_id: str) -> pd.DataFrame:
         """
-        dept_model = DepartmentMasterUpdate(**data)
-
-        if self.nmbrs.mock_mode:
-            return dept_model
-
-        try:
-            DepartmentType = self.nmbrs.soap_client_debtors.get_type('ns0:Department')
-            soap_department = DepartmentType(
-                Id=dept_model.department_id,
-                Code=dept_model.code,
-                Description=dept_model.description
-            )
-
-            response = self.nmbrs.soap_client_debtors.service.Department_Update(
-                DebtorId=dept_model.debtor_id,
-                department=soap_department,
-                _soapheaders={'AuthHeaderWithDomain': self.nmbrs.soap_auth_header_debtors}
-            )
-            return response
-
-        except Fault as e:
-            raise Exception(f"SOAP request failed: {str(e)}")
-        except Exception as e:
-            raise Exception(f"Failed to update Department: {str(e)}")
-
-    def delete(self, data: Dict[str, Any]):
+        Internal method to get departments for a single debtor.
         """
-        Delete a master department for a debtor using SOAP API.
+        request = requests.Request(method='GET',
+                                   url=f"{self.nmbrs.base_url}debtors/{debtor_id}/departments")
 
-        Args:
-            data: Dictionary containing department data with fields matching DepartmentMasterDelete schema:
-                - debtor_id: Debtor ID
-                - department_id: Department ID to delete
+        data = self.nmbrs.get_paginated_result(request)
 
-        Returns:
-            Response from the API
-        """
-        dept_model = DepartmentMasterDelete(**data)
+        df = pd.DataFrame(data)
+        df['debtorId'] = debtor_id
 
-        if self.nmbrs.mock_mode:
-            return True
-
-        try:
-            response = self.nmbrs.soap_client_debtors.service.Department_Delete(
-                DebtorId=dept_model.debtor_id,
-                id=dept_model.department_id,
-                _soapheaders={'AuthHeaderWithDomain': self.nmbrs.soap_auth_header_debtors}
-            )
-            return response
-
-        except Fault as e:
-            raise Exception(f"SOAP request failed: {str(e)}")
-        except Exception as e:
-            raise Exception(f"Failed to delete Department: {str(e)}")
+        return df

brynq_sdk_nmbrs/document.py

@@ -1,6 +1,6 @@
-from io import BytesIO
 import base64
-from typing import Dict, Any, Union
+from io import BytesIO
+from typing import Any, BinaryIO, Dict, Optional
 
 import pandas as pd
 import requests
@@ -11,7 +11,7 @@ from .schemas.document import DocumentUpload
 
 class EmployeeDocument:
     """Handle employee document operations via SOAP API."""
-    
+
     def __init__(self, nmbrs):
         self.nmbrs = nmbrs
 
@@ -55,13 +55,31 @@ class EmployeeDocument:
 
 
 class Payslip:
+    """
+    Class for handling employee payslips.
+
+    Endpoints:
+        - GET /api/employees/{employeeId}/payslipperperiod
+    """
+
     def __init__(self, nmbrs):
         self.nmbrs = nmbrs
 
     def get(self,
             employee_id: str,
             period: int = None,
-            year: int = None) -> pd.DataFrame:
+            year: int = None) -> BytesIO:
+        """
+        Get an employee payslip per period.
+
+        Args:
+            employee_id: The ID of the employee
+            period: Optional period number
+            year: Optional year
+
+        Returns:
+            BytesIO containing the payslip PDF
+        """
         params = {}
         if period:
             params['period'] = period
@@ -78,3 +96,176 @@ class Payslip:
         return BytesIO(resp.content)
 
 
+class Document:
+    """
+    Class for handling employee documents.
+
+    Endpoints:
+        - GET /api/employees/{employeeId}/annualstatement
+        - GET /api/employees/{employeeId}/documents/types
+        - GET /api/employees/{employeeId}/documents/folders
+        - POST /api/employees/{employeeId}/documents
+        - GET /api/documents/{taskId}
+    """
+
+    def __init__(self, nmbrs):
+        self.nmbrs = nmbrs
+
+    def get_annual_statement(self, employee_id: str, year: Optional[int] = None) -> BytesIO:
+        """
+        Get an employee annual statement for the given year.
+
+        Args:
+            employee_id: The ID of the employee
+            year: Optional year filter
+
+        Returns:
+            BytesIO containing the annual statement PDF
+        """
+        params = {}
+        if year is not None:
+            params['year'] = year
+
+        resp = self.nmbrs.session.get(
+            f"{self.nmbrs.base_url}employees/{employee_id}/annualstatement",
+            params=params,
+            timeout=self.nmbrs.timeout
+        )
+        resp.raise_for_status()
+        task_id = resp.json()['taskId']
+
+        # Retrieve the actual document content
+        resp = self.nmbrs.session.get(
+            f"{self.nmbrs.base_url}documents/{task_id}",
+            timeout=self.nmbrs.timeout
+        )
+
+        return BytesIO(resp.content)
+
+    def get_types(self, employee_id: str) -> pd.DataFrame:
+        """
+        Get the document types available for a specific employee.
+
+        Args:
+            employee_id: The ID of the employee
+
+        Returns:
+            DataFrame containing document types
+        """
+        request = requests.Request(
+            method='GET',
+            url=f"{self.nmbrs.base_url}employees/{employee_id}/documents/types"
+        )
+
+        data = self.nmbrs.get_paginated_result(request)
+        return pd.DataFrame(data)
+
+    def get_folders(self, employee_id: str) -> pd.DataFrame:
+        """
+        Get document folders for a specific employee.
+
+        Args:
+            employee_id: The ID of the employee
+
+        Returns:
+            DataFrame containing document folders
+        """
+        request = requests.Request(
+            method='GET',
+            url=f"{self.nmbrs.base_url}employees/{employee_id}/documents/folders"
+        )
+
+        data = self.nmbrs.get_paginated_result(request)
+        return pd.DataFrame(data)
+
+    def upload(self,
+               employee_id: str,
+               file: BinaryIO,
+               file_name: str,
+               file_extension: str,
+               document_type: str,
+               description: Optional[str] = None,
+               number: Optional[str] = None,
+               is_visible_for_employee: Optional[bool] = None,
+               folder: Optional[str] = None,
+               valid_from: Optional[str] = None,
+               valid_to: Optional[str] = None):
+        """
+        Upload a document for a specific employee.
+
+        Args:
+            employee_id: The ID of the employee
+            file: Binary file content to upload
+            file_name: Name of the file
+            file_extension: Extension of the file (e.g., "pdf", "docx")
+            document_type: Type of the document
+            description: Optional description of the document
+            number: Optional document number
+            is_visible_for_employee: Optional flag if document is visible for employee
+            folder: Optional folder UUID to place document in
+            valid_from: Optional valid from date (ISO format)
+            valid_to: Optional valid to date (ISO format)
+
+        Returns:
+            Response from the API
+        """
+        if self.nmbrs.mock_mode:
+            return {
+                'employee_id': employee_id,
+                'file_name': file_name,
+                'file_extension': file_extension,
+                'document_type': document_type,
+                'description': description
+            }
+
+        # Prepare multipart form data
+        files = {
+            'file': (file_name, file)
+        }
+
+        data = {
+            'fileName': file_name,
+            'fileExtension': file_extension,
+            'type': document_type
+        }
+
+        if description is not None:
+            data['description'] = description
+        if number is not None:
+            data['number'] = number
+        if is_visible_for_employee is not None:
+            data['isVisibleForEmployee'] = str(is_visible_for_employee).lower()
+        if folder is not None:
+            data['folder'] = folder
+        if valid_from is not None:
+            data['validFrom'] = valid_from
+        if valid_to is not None:
+            data['validTo'] = valid_to
+
+        resp = self.nmbrs.session.post(
+            url=f"{self.nmbrs.base_url}employees/{employee_id}/documents",
+            data=data,
+            files=files,
+            timeout=self.nmbrs.timeout
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_content(self, task_id: str) -> BytesIO:
+        """
+        Get document content by task ID.
+
+        Use this to retrieve documents after getting a task ID from other endpoints.
+
+        Args:
+            task_id: The task ID from a previous document request
+
+        Returns:
+            BytesIO containing the document content
+        """
+        resp = self.nmbrs.session.get(
+            f"{self.nmbrs.base_url}documents/{task_id}",
+            timeout=self.nmbrs.timeout
+        )
+
+        return BytesIO(resp.content)

brynq_sdk_nmbrs/employee_wage_tax_settings.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 import pandas as pd
 import requests
@@ -16,7 +16,9 @@ class EmployeeWageTaxSettings:
         self.nmbrs = nmbrs
 
     def get(self,
-            employee_id: str = None) -> tuple[pd.DataFrame, pd.DataFrame]:
+            company_id: Optional[str] = None,
+            employee_id: str = None,
+            created_from: Optional[str] = None) -> tuple[pd.DataFrame, pd.DataFrame]:
         """
         Get wage tax settings history for employees in companies.
 
@@ -27,8 +29,11 @@ class EmployeeWageTaxSettings:
             Tuple of (valid_data, invalid_data) DataFrames
         """
         wage_tax_settings = pd.DataFrame()
-        for company in self.nmbrs.company_ids:
-            wage_tax_settings = pd.concat([wage_tax_settings, self._get(company, employee_id)])
+        if company_id:
+            wage_tax_settings = self._get(company_id, employee_id, created_from)
+        else:
+            for company in self.nmbrs.company_ids:
+                wage_tax_settings = pd.concat([wage_tax_settings, self._get(company, employee_id, created_from)])
 
         valid_settings, invalid_settings = Functions.validate_data(
             df=wage_tax_settings, schema=EmployeeWageTaxSettingsGet, debug=True
@@ -38,7 +43,8 @@ class EmployeeWageTaxSettings:
 
     def _get(self,
              company_id: str,
-             employee_id: str = None) -> pd.DataFrame:
+             employee_id: str = None,
+             created_from: Optional[str] = None) -> pd.DataFrame:
         """
         Get wage tax settings history for a specific company.
 
@@ -52,6 +58,8 @@ class EmployeeWageTaxSettings:
         params = {}
         if employee_id:
             params['employeeId'] = employee_id
+        if created_from is not None:
+            params['createdFrom'] = created_from
 
         request = requests.Request(
             method='GET',