voipms-api 1.0.0b9__tar.gz

voipms_api-1.0.0b9/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2024 Jose Pineda joseanmont.info
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

voipms_api-1.0.0b9/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.1
+Name: voipms-api
+Version: 1.0.0b9
+Summary: A python package to simplify the use of the VoIP.ms API
+Author-email: Jose Pineda <hello@joseanmont.com>
+Project-URL: Homepage, https://github.com/joseanmont/voipms-api
+Project-URL: Issues, https://github.com/joseanmont/voipms-api/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32.3
+
+# voipms-api
+
+This package is developed to streamline the process of integrating with the VoIP.ms API, allowing developers to focus on implementing functionality without the need to write boilerplate code for API connectivity and function calls. The VoIP.ms API Client encapsulates all necessary code to connect and interact with the VoIP.ms API, enabling developers to call functions directly.
+
+## Features
+
+- **Simplified Integration**: Connect to the VoIP.ms API with minimal setup.
+- **Modular Design**: Organized into separate modules for different functionalities, allowing targeted imports and reduced overhead.
+- **Ongoing Development**: New functions will continue to be added.
+
+## Installation
+
+Add the package to your project to be able to import its modules, classes and methods.
+
+Check requirements.txt to see the packages that need to be installed.
+
+**Note:** If you have problems importing the modules, add the path to the directory and subdirectories in PYTHONPATH.
+
+## Package structure
+
+```plaintext
+voipms-api
+├── src/
+│   └── voipms-api/
+│       ├── __init__.py
+│       ├── accounts.py
+│       ├── call_hunting.py
+│       ├── dids.py
+│       ├── forwarding.py
+│       ├── general.py
+│       ├── ivr.py
+│       ├── lnp.py
+│       ├── ring_groups.py
+│       ├── sms.py
+│       ├── voicemail.py
+│       └── voipms_client.py
+│── tests/
+│   └── test_voipms_client.py
+```
+
+## Usage
+
+The credentials can be loaded on your virtual enviroment by adding the following variables on an .env file:
+
+```.env
+VOIPMS_API_USER = "Your VoIP.ms account email"
+VOIPMS_API_PASSWORD = "Your VoIP.ms API password"
+```
+
+However, you can also add your credentials or use different credentials by using the class VoipMsClient. Here is an example:
+
+```
+from voipms_api import VoipMsClient
+vms_client = VoipMsClient(username="me@email.com", password="your VoIP.ms API password")
+```
+
+Or, you can do it when calling a single instance. For example:
+
+```
+from voipms_api import General
+balance = General(username="me@email.com", password="api_password")
+print(balance.get_balance())
+```
+
+## Module Capabilities
+
+Currently, the modules of accounts and voice features within the voipms-api package provide basic functionalities for creating, retrieving, and deleting items. 
+
+You will find the current available functions in the description of each class.
+
+Additional functionalities will be added over time.
+
+## Examples of scripts
+
+You can find more example scripts in the examples directory. These scripts demonstrate how to use the some features of the voipms-api package.
+
+## Contributing
+
+Currently, we are not accepting collaborations. However, if you have suggestions or feedback, feel free to contact us. Issues can be reported on GitHub.
+
+## License
+
+This package is free to use and can be included in any project. See the LICENSE file for more details.
+
+## Support
+
+For any issues or questions, please raise an issue on GitHub or contact us directly at hello@joseanmont.info
+
+## Special Thanks
+
+Kudos to the VoIP.ms development team. They have developed an understandable, simple but still powerful API that lets users take their VoIP system beyond limits.

voipms_api-1.0.0b9/README.md

@@ -0,0 +1,91 @@
+# voipms-api
+
+This package is developed to streamline the process of integrating with the VoIP.ms API, allowing developers to focus on implementing functionality without the need to write boilerplate code for API connectivity and function calls. The VoIP.ms API Client encapsulates all necessary code to connect and interact with the VoIP.ms API, enabling developers to call functions directly.
+
+## Features
+
+- **Simplified Integration**: Connect to the VoIP.ms API with minimal setup.
+- **Modular Design**: Organized into separate modules for different functionalities, allowing targeted imports and reduced overhead.
+- **Ongoing Development**: New functions will continue to be added.
+
+## Installation
+
+Add the package to your project to be able to import its modules, classes and methods.
+
+Check requirements.txt to see the packages that need to be installed.
+
+**Note:** If you have problems importing the modules, add the path to the directory and subdirectories in PYTHONPATH.
+
+## Package structure
+
+```plaintext
+voipms-api
+├── src/
+│   └── voipms-api/
+│       ├── __init__.py
+│       ├── accounts.py
+│       ├── call_hunting.py
+│       ├── dids.py
+│       ├── forwarding.py
+│       ├── general.py
+│       ├── ivr.py
+│       ├── lnp.py
+│       ├── ring_groups.py
+│       ├── sms.py
+│       ├── voicemail.py
+│       └── voipms_client.py
+│── tests/
+│   └── test_voipms_client.py
+```
+
+## Usage
+
+The credentials can be loaded on your virtual enviroment by adding the following variables on an .env file:
+
+```.env
+VOIPMS_API_USER = "Your VoIP.ms account email"
+VOIPMS_API_PASSWORD = "Your VoIP.ms API password"
+```
+
+However, you can also add your credentials or use different credentials by using the class VoipMsClient. Here is an example:
+
+```
+from voipms_api import VoipMsClient
+vms_client = VoipMsClient(username="me@email.com", password="your VoIP.ms API password")
+```
+
+Or, you can do it when calling a single instance. For example:
+
+```
+from voipms_api import General
+balance = General(username="me@email.com", password="api_password")
+print(balance.get_balance())
+```
+
+## Module Capabilities
+
+Currently, the modules of accounts and voice features within the voipms-api package provide basic functionalities for creating, retrieving, and deleting items. 
+
+You will find the current available functions in the description of each class.
+
+Additional functionalities will be added over time.
+
+## Examples of scripts
+
+You can find more example scripts in the examples directory. These scripts demonstrate how to use the some features of the voipms-api package.
+
+## Contributing
+
+Currently, we are not accepting collaborations. However, if you have suggestions or feedback, feel free to contact us. Issues can be reported on GitHub.
+
+## License
+
+This package is free to use and can be included in any project. See the LICENSE file for more details.
+
+## Support
+
+For any issues or questions, please raise an issue on GitHub or contact us directly at hello@joseanmont.info
+
+## Special Thanks
+
+Kudos to the VoIP.ms development team. They have developed an understandable, simple but still powerful API that lets users take their VoIP system beyond limits.

voipms_api-1.0.0b9/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=71.1.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "voipms-api"
+version = "1.0.0b9"
+authors = [{ name = "Jose Pineda", email = "hello@joseanmont.com" }]
+description = "A python package to simplify the use of the VoIP.ms API"
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = ["requests>=2.32.3"]
+
+
+[project.urls]
+Homepage = "https://github.com/joseanmont/voipms-api"
+Issues = "https://github.com/joseanmont/voipms-api/issues"

voipms_api-1.0.0b9/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

voipms_api-1.0.0b9/src/tests/test_voipms_client.py

@@ -0,0 +1,17 @@
+import unittest
+from voipms_api import VoipMsClient
+
+class TestVoIPmsClient(unittest.TestCase):
+
+    def test_connection(self):
+        """
+        Tests if the credentials and IP address are correct.
+        """
+        client = VoipMsClient()
+        result = client.test_connection()
+        self.assertEqual(result["status"], "success")
+
+
+if __name__ == "__main__":
+    
+    unittest.main()

voipms_api-1.0.0b9/src/voipms_api/__init__.py

@@ -0,0 +1,25 @@
+from .accounts import Accounts
+from .call_hunting import CallHunting
+from .dids import DIDs
+from .forwarding import Forwarding
+from .general import General
+from .ivr import IVR
+from .lnp import LNP
+from .ring_groups import RingGroups
+from .sms import SMS
+from .voicemail import Voicemail
+from .voipms_client import VoipMsClient
+
+__all__ = [
+    "Accounts",
+    "CallHunting",
+    "DIDs", 
+    "Forwarding", 
+    "General",
+    "IVR", 
+    "LNP", 
+    "RingGroups",
+    "SMS", 
+    "Voicemail", 
+    "VoipMsClient"
+]

voipms_api-1.0.0b9/src/voipms_api/accounts.py

@@ -0,0 +1,161 @@
+import requests
+from typing import Optional, Union
+
+
+class Accounts():
+    '''
+    A class to call the Sub Accounts functions of the VoIP.ms API.
+
+    Methods:
+        create_subaccount:
+            Creates a Sub Account and returns the result of the request.
+    '''
+
+    def __init__(self, username=None, password=None) -> None:
+
+        from voipms_api import VoipMsClient
+        
+        if (username and not password) or (password and not username):
+            raise ValueError("Both username and password must be provided together")
+        elif(username and password):
+            self.username = username
+            self.password = password
+            self.vms_client = VoipMsClient(self.username, self.password)
+        else:
+            self.vms_client = VoipMsClient()
+
+    
+    def create_subaccount(self, 
+            username:str,
+            password:str,
+            extension:Optional[Union[str, int]]=None,
+            protocol:Optional[Union[str, int]]=1,
+            auth_type:Optional[Union[str, int]]=1,
+            device_type:Optional[Union[str, int]]=2,
+        ) -> dict:
+        """
+        Calls the VoIP.ms createSubAccount function.
+
+        Args:
+            username (str, required): Username to set to the sub account (Example: 'VoIP').
+            password (str, required): Password to set for the authentication.
+            extension str or int, optional): Sub Account Internal Extension (Example: 1 -> Creates 101).
+            protocol (str or int, optional): The protocol the sub account will use. Default is '1' for SIP (value from get_Protocols).
+            auth_type (str or int, optional): The authentication type the sub account will use. Default is '1' for User/Password (value from get_auth_types).
+            device_type (str or int, optional): Device type that will be used. Default is '2' for ATA device, IP Phone or Softphone (value from get_device_types).
+
+        Returns:
+            dict: A dictionary containing the status of the request and the Sub Account that was created.
+        """
+        
+        mtd = "createSubAccount"
+
+        try:
+            params = {
+
+                # Required by this package.
+                "username": username,
+                "password": password,
+
+                # Required by the VoIP.ms API but set with default values in this package.
+                "lock_international": 1,
+                "international_route": 1,
+                "music_on_hold": "default",
+                "allowed_codecs": "g722",
+                "dtmf_mode": "auto",
+                "nat": "yes",
+            }
+
+            # Optional parameters in this package.
+            if protocol:
+                params["protocol"] = protocol
+            if auth_type:
+                params["auth_type"] = auth_type
+            if device_type:
+                params["device_type"] = device_type
+            if extension:
+                params["internal_extension"] = extension
+            
+            data = self.vms_client.make_request(mtd, params)
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None
+        
+
+    def delete_subaccount(self, 
+            id:Union[str, int],
+        ) -> dict:
+        """
+        Calls the VoIP.ms delSubAccount function.
+
+        Args:
+            id (str or int, required): ID of the Sub Account that will be deleted(Example: '99785' or 99785). Value from get_subaccounts.
+
+        Returns:
+            dict: A dictionary containing the status of the request and the Sub Account that was canceled.
+        """
+        
+        mtd = "delSubAccount"
+
+        try:
+            params = {
+                "id": id,
+            }
+            
+            data = self.vms_client.make_request(mtd, params)
+            data["result"] = "Sub Account deleted"
+            data["id"] = id
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None
+        
+
+    def get_subaccounts(self, 
+            subaccount:Optional[Union[str, int]]=None
+        ) -> dict:
+        """
+        Calls the VoIP.ms getSubAccounts function.
+
+        Args:
+            subaccount (str or int, optional): Sub Account ID or username (Example: '100000_SubAccount' or 99785).
+
+        Returns:
+            dict: A dictionary containing the status of the request and the Sub Accounts and their data, or a specific Sub Account data if an ID or username is provided.
+        """
+        
+        mtd = "getSubAccounts"
+
+        try:
+            params = {}
+
+            if subaccount:
+                params["account"] = subaccount
+            
+            data = self.vms_client.make_request(mtd, params)
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None

voipms_api-1.0.0b9/src/voipms_api/call_hunting.py

@@ -0,0 +1,173 @@
+import requests
+from typing import Optional, Union
+
+class CallHunting():
+    '''
+    A class to call the Call Hunting functions of the VoIP.ms API.
+
+    Methods:
+        create_call_hunting:
+            Creates a new Call Hunting and returns the result of the request.
+        delete_call_hunting:
+            Deletes a specific Call Hunting and returns the result of the request.
+        get_call_hunting:
+            Returns all the existing Call Huntings, or a specific Call Hunting if a Call Hunting ID is provided.
+    '''
+
+    def __init__(self, username=None, password=None) -> None:
+
+        from voipms_api import Accounts, VoipMsClient
+        
+        if (username and not password) or (password and not username):
+            raise ValueError("Both username and password must be provided together")
+        elif(username and password):
+            self.username = username
+            self.password = password
+            self.vms_client = VoipMsClient(self.username, self.password)
+        else:
+            self.vms_client = VoipMsClient()
+
+        # Code to get the Account number to set the Main Account as the default member so it is not required.
+        accounts = Accounts()
+        get_accounts = accounts.get_subaccounts()
+        self.acc_number = get_accounts['accounts'][0]['account']
+        self.acc_number = self.acc_number[0:6]
+
+
+    def create_call_hunting(self, 
+            name:str,
+            recording:Optional[Union[str, int]]=None,
+            language:Optional[str]=None,
+            order:Optional[str]=None,
+            members:Optional[str]=None,
+        ) -> dict:
+        """
+        Calls the VoIP.ms setCallHunting function to create a new Call Hunting.
+
+        Args:
+            name (str, required): A name for the new Call Hunting.
+            recording (str or int, optional): ID of the recording to set to the Call Hunting. Values from get_recordings.
+            language (str, optional): Language of the Call Hunting. Default  is 'en' for English. Values from get_languages.
+            order (str, optional): Ring order of the Call Hunting. Default  is 'follow' to follow member's order. Alternative is 'random'.
+            members (srt, optional): A string of members separated by semicolons. Default is Main Account as only member. (Example: 'account:100001;fwd:16006'). See VoIP.ms API documentation for more details.
+
+        Returns:
+            dict: A dictionary containing the status of the request and the name of the Call Hunting that was created.
+        """
+        
+        mtd = "setCallHunting"
+        main_account = "account:" + self.acc_number
+
+        try:
+            params = {
+                # Required by this package
+                "description": name,
+
+                # Required by VoIP.ms API but set with default values so it is not required in this package.
+                "music": "default",
+                "recording": "default",
+                "language": "en",
+                "order": "follow",
+                "members": main_account,
+                "ring_time": 25,
+                "press": 0
+            }
+
+            # Optional in this package.
+            if recording:
+                params["recording"] = recording
+            if language:
+                params["language"] = language
+            if order:
+                params["order"] = order
+            if members:
+                params["members"] = members
+            
+            data = self.vms_client.make_request(mtd, params)
+            data["name"] = name
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None
+        
+
+    def delete_call_hunting(self, 
+            call_hunting:Union[str, int],
+        ) -> dict:
+        """
+        Calls the VoIP.ms delCallHunting function.
+
+        Args:
+            call_hunting (str or int, required): ID of the call hunting that will be deleted (Example: 18635). Value from get_call_huntings.
+
+        Returns:
+            dict: A dictionary containing the status of the request and the ID of the call hunting that was deleted.
+        """
+        
+        mtd = "delCallHunting"
+
+        try:
+            params = {
+                "callhunting": call_hunting,
+            }
+
+            # Code to get the name of the call hunting that is deleted.
+            ch_info = self.get_call_huntings(call_hunting)
+            ch_name = ch_info["call_hunting"][0]["description"]
+
+            data = self.vms_client.make_request(mtd, params)
+            data["call_hunting"] = ch_name
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None
+        
+
+    def get_call_huntings(self, 
+            call_hunting:Optional[Union[str, int]]=None,
+        ) -> dict:
+        """
+        Calls the VoIP.ms getCallHuntings function.
+
+        Args:
+            call_hunting (str or int, optional): ID of a specific call hunting (Example: 323).
+
+        Returns:
+            dict: A dictionary containing the status of the request and the data of all the call huntings, or the data of a specific call hunting if an ID is provided.
+        """
+        
+        mtd = "getCallHuntings"
+
+        try:
+            params = {}
+
+            # Optional in this package.
+            if call_hunting:
+                params["callhunting"] = call_hunting
+            
+            data = self.vms_client.make_request(mtd, params)
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None