From 85293e760637888d23c9452b97c70c99188e13ad Mon Sep 17 00:00:00 2001
From: KiPageFault <157066925+KiPageFault@users.noreply.github.com>
Date: Tue, 19 Nov 2024 10:30:05 +0000
Subject: [PATCH] 131 locate free extensions (#139)

Co-authored-by: CHOPP3D <64507146+Chopped4Life@users.noreply.github.com>
---
 odins_spear/exceptions.py                    | 17 ++++++++-
 odins_spear/scripter.py                      | 15 ++++++++
 odins_spear/scripts/__init__.py              |  1 +
 odins_spear/scripts/locate_free_extension.py | 40 ++++++++++++++++++++
 4 files changed, 71 insertions(+), 2 deletions(-)
 create mode 100644 odins_spear/scripts/locate_free_extension.py

diff --git a/odins_spear/exceptions.py b/odins_spear/exceptions.py
index 6c8df1a..b33fc08 100644
--- a/odins_spear/exceptions.py
+++ b/odins_spear/exceptions.py
@@ -113,8 +113,22 @@ class OSInvalidPasswordType(OSError):
     """
 
     def __str__(self) -> str:
-        return f"Invalid or unsupported password, please review supported passwords."   
+        return f"Invalid or unsupported password, please review supported passwords."  
+
+class OSExtensionNotFound(OSError):
+    """ Raised when a searched extension is not found
+    """ 
+
+    def __str__(self) -> str:
+        return f"Cannot locate extension. Please alter search criteria"
     
+class OSRangeFault(OSError):
+    """ Raised when a numeric range is invalid to the context provided, 
+        E.G: uninitialised range values, disordered range values.
+    """
+
+    def __str__(self):
+        return f"Range fault raised. Please verify integrity of passed range values"
 
 class OSServiceNotAssigned(OSError):
     """ Raised a service needed is not assigned to a Broadworks entity.  
@@ -123,7 +137,6 @@ class OSServiceNotAssigned(OSError):
     def __str__(self) -> str:
         return f"Service not assigend to target Broadworks entity. Please check services assigned."   
 
-
 class OSFileNotFound(OSError):
     """ Raised when a file can not be found.  
     """
diff --git a/odins_spear/scripter.py b/odins_spear/scripter.py
index 2ddd0fc..d2eec25 100644
--- a/odins_spear/scripter.py
+++ b/odins_spear/scripter.py
@@ -167,6 +167,21 @@ def remove_numbers(self, service_provider_id: str, group_id: str, start_of_range
         return scripts.remove_numbers.main(self.api, service_provider_id, group_id, start_of_range_number, 
                        end_of_range_number)
         
+    def locate_free_extension( self, service_provider_id: str, group_id: str, range_start: int, range_end: int ):
+        """Locates the lowest value free extension given the provided range of extension numbers.
+
+        Raises: OSExtensionNotFound: Raises when a free extension is not located within the passed range.
+
+        Args:
+            service_provider_id (str): Service Provider/ Enterprise ID where Group is located which hosts needed free extensions
+            group_id (str): Group ID where target extensions are located.
+            range_start (int): integral value specifying the starting range for free extensions
+            range_end (int): integral value specifying the ending range for free extensions
+
+        Returns:
+            JSON: JSON data of the free extension {extension: "1000"}
+        """
+        return scripts.locate_free_extension.main( self.api, service_provider_id, group_id, range_start, range_end )
     
     def service_provider_trunking_capacity(self, service_provider_id: str):
         """Returns a JSON breakdown of the Trunking Call Capacity of a Service Provider/ Enterprise (SP/ENT). 
diff --git a/odins_spear/scripts/__init__.py b/odins_spear/scripts/__init__.py
index 171649d..f342d8b 100644
--- a/odins_spear/scripts/__init__.py
+++ b/odins_spear/scripts/__init__.py
@@ -25,3 +25,4 @@
 from .user_activity import main
 from .user_association import main
 from .webex_builder import main
+from .locate_free_extension import main
diff --git a/odins_spear/scripts/locate_free_extension.py b/odins_spear/scripts/locate_free_extension.py
new file mode 100644
index 0000000..4aa22a7
--- /dev/null
+++ b/odins_spear/scripts/locate_free_extension.py
@@ -0,0 +1,40 @@
+from exceptions import OSExtensionNotFound, OSRangeFault
+
+def retrieve_extensions( api, service_provider_id: str, group_id: str ) -> list:
+    
+    extensions = []
+
+    dataset = (
+       api.get.users( service_provider_id, group_id              ) +
+       api.get.group_hunt_groups( service_provider_id, group_id  ) +
+       api.get.group_call_centers( service_provider_id, group_id ) +
+       api.get.auto_attendants( service_provider_id, group_id    )
+    )
+
+    for data in dataset:
+        if not data['extension']:
+            continue
+
+        extensions.append( int(data['extension']) )
+
+    return extensions if extensions else None
+
+def main( api, service_provider_id: str, group_id: str, range_start: int, range_end: int ):
+    '''Retrieves The Lowest Free Extension Available In The Designated Group Passed.
+    '''
+
+    if range_start > range_end:
+        raise OSRangeFault
+
+    # Retrieve List Of Occupied Extensions Within The Group
+    extensions = retrieve_extensions(
+        api,
+        service_provider_id,
+        group_id,
+    )
+
+    for extension in range(range_start, range_end + 1):
+        if extension not in extensions:
+            return {'extension': extension}
+
+    raise OSExtensionNotFound
\ No newline at end of file