vobiz-python 0.1.0__py3-none-any.whl

vobiz/__init__.py

@@ -0,0 +1,4 @@
+from .rest.client import Client as RestClient
+from . import xml as vobizxml
+
+__all__ = ["RestClient", "vobizxml"]

vobiz/base.py

@@ -0,0 +1,237 @@
+# -*- coding: utf-8 -*-
+"""
+Base classes, used to deal with every Vobiz resource.
+"""
+
+import pprint
+
+from vobiz.exceptions import InvalidRequestError
+
+
+class Meta:
+    def __init__(self):
+        self.limit = None
+        self.next = None
+        self.offset = None
+        self.previous = None
+        self.total_count = None
+
+
+class VobizGenericResponse(object):
+    """A generic response to cover it all!
+
+    This provides a generic blanket response based on what is received from
+    Vobiz servers.
+
+    This will be used only during POST and DELETE requests.
+    """
+
+    def __init__(self, params_dict, id_string=None):
+        for i in params_dict:
+            self.__dict__[i] = params_dict[i]
+
+        if id_string and id_string in params_dict:
+            self.__dict__['id'] = params_dict[id_string]
+
+
+class ResponseObject(object):
+    def __init__(self, dct):
+        self.__dict__.update(dct)
+
+    def __contains__(self, item):
+        return item in self.__dict__
+
+    def __getitem__(self, item):
+        try:
+            return self.__dict__.__getitem__(item)
+        except KeyError:
+            return self.objects.__getitem__(item)
+
+    def __setitem__(self, key, value):
+        self.__dict__.__setitem__(key, value)
+
+    def __delitem__(self, key):
+        del self.__dict__[key]
+
+    def __str__(self):
+        return pprint.pformat(self.__dict__)
+
+    def __repr__(self):
+        return pprint.pformat(self.__dict__)
+
+
+class ListResponseObject(ResponseObject):
+    def __init__(self, client, dct):
+        super(ListResponseObject, self).__init__(dct)
+
+    def __iter__(self):
+        return self.objects.__iter__()
+
+    def __len__(self):
+        return len(self.objects)
+
+    def __str__(self):
+        return pprint.pformat(self.objects)
+
+    def __repr__(self):
+        return str([object for object in self.objects])
+
+
+class VobizResource(ResponseObject):
+    """The Vobiz resource object
+
+    This provides an interface to deal with all Vobiz resources and
+    sub-resources.
+    """
+
+    _identifier_string = None
+
+    @property
+    def id(self):
+        value = self.__dict__.get(self._identifier_string, None)
+        if not value:
+            raise ValueError('{} must be set'.format(self._identifier_string))
+        return value
+
+    def __init__(self, client, data):
+        """Sets up the resource URI along with a hack for Account resource"""
+
+        super(VobizResource, self).__init__(data)
+        self._name = self._name or self.__class__.__name__
+        self.client = client
+
+    def __str__(self):
+        return pprint.pformat(self.__dict__)
+
+    def __repr__(self):
+        return self.__str__()
+
+    def update(self, params, path, **kwargs):
+        self.client.request('POST', params, path, **kwargs)
+
+    def _update(self, params):
+        if not self.id:
+            raise InvalidRequestError(
+                'Cannot update a {resource_type} resource without an '
+                'identifier'.format(resource_type=self._name))
+
+        response_json = self.client.send_request(
+            self.__resource_uri, method='POST', data=params)
+
+        for key in params:
+            self.__dict__[key] = params[key]
+
+        for key in response_json:
+            self.__dict__[key] = response_json[key]
+
+        return self
+
+    def _execute_action(self,
+                        action=None,
+                        method='GET',
+                        params=None,
+                        parse=False):
+        if not action:
+            response = self.client.send_request(
+                self.__resource_uri, method=method, data=params)
+        else:
+            response = self.client.send_request(
+                self.__resource_uri + action + '/', method=method, data=params)
+
+        if not parse:
+            return response
+
+        self.__resource_json = response
+        self.__parse_json()
+
+        try:
+            self.id = response[self._identifier_string]
+        except AttributeError:
+            pass
+
+        if method == 'POST':
+            self.__resource_json = params
+            self.__parse_json()
+        return self
+
+    def delete(self):
+        if not self.id:
+            raise InvalidRequestError(
+                'Cannot delete a {resource_type} resource without an '
+                'identifier'.format(resource_type=self._name))
+
+        return VobizGenericResponse(
+            self.client.send_request(self.__resource_uri, method='DELETE'))
+
+    def get(self):
+        if not self.id:
+            raise InvalidRequestError(
+                'Cannot get a {resource_type} resource without an '
+                'identifier'.format(resource_type=self._name))
+
+        self.__resource_json = self.client.send_request(self.__resource_uri)
+        self.__parse_json()
+        return self
+
+    def create(self, params):
+        if self.id:
+            raise InvalidRequestError(
+                'Cannot create a {resource_type} resource because another'
+                ' {resource_type} resource exists with the same '
+                'identifier: {identifier}.'.format(
+                    resource_type=self._name, identifier=self.id))
+
+        id_string = None
+        if self._identifier_string:
+            id_string = self._identifier_string
+
+        return VobizGenericResponse(
+            self.client.send_request(
+                self.__resource_uri, data=params, method='POST'), id_string)
+
+
+class SecondaryVobizResource(VobizResource):
+    """
+    SecondaryVobizResource resource object.
+    Provides an interface to deal with resources where the identifier
+    has a mid-level parent.
+    """
+    _secondary_identifier_string = None
+
+    @property
+    def secondary_id(self):
+        value = self.__dict__.get(self._secondary_identifier_string, None)
+        if not value:
+            raise ValueError('{} must be set'.format(self._secondary_identifier_string))
+        return value
+
+    def __init__(self, client, data):
+        super(VobizResource, self).__init__(client, data)
+        self._name = self._name or self.__class__.__name__
+        self.client = client
+
+
+class VobizResourceInterface(object):
+    _iterable = True
+
+    def __init__(self, client, **kwargs):
+        self.client = client
+
+    def __iter__(self):
+        if not getattr(self, 'list') or not self.__class__._iterable:
+            raise NotImplementedError(
+                'list is not supported for this resource')
+
+        def gen():
+            limit = 20
+            offset = 0
+            while True:
+                response = self.list(limit=limit, offset=offset)
+                if not response.objects:
+                    return
+
+                for item in response:
+                    yield item
+                offset += limit
+
+        return gen()

vobiz/exceptions.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+class VobizRestError(Exception):
+    pass
+
+
+class AuthenticationError(VobizRestError):
+    pass
+
+
+class InvalidRequestError(VobizRestError):
+    pass
+
+
+class VobizServerError(VobizRestError):
+    pass
+
+
+class VobizXMLError(VobizRestError):
+    pass
+
+
+class ResourceNotFoundError(VobizRestError):
+    pass
+
+
+class ValidationError(VobizRestError):
+    pass
+
+
+class ForbiddenError(VobizRestError):
+    pass
+
+class GeoPermissionError(VobizRestError):
+    pass

vobiz/resources/__init__.py

@@ -0,0 +1,12 @@
+from .accounts import Accounts
+from .subaccounts import Subaccounts
+from .calls_vobiz import Calls
+from .applications import Applications
+from .recordings import Recordings
+from .cdrs import CDRs
+from .numbers import PhoneNumbers
+from .endpoints import Endpoints
+from .sip_trunks import SipTrunks
+from .credentials import Credentials
+from .ip_access_control_lists import IpAccessControlLists
+from .origination_uris import OriginationUris

vobiz/resources/accounts.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+"""
+Vobiz Accounts resource.
+
+Implements only the endpoints defined in the Vobiz accounts documentation.
+"""
+
+VOBIZ_API_V1 = "https://api.vobiz.ai/api/v1"
+
+
+class Accounts:
+    def __init__(self, client):
+        self.client = client
+
+    def get(self):
+        """
+        GET https://api.vobiz.ai/api/v1/auth/me
+        """
+        url = f"{VOBIZ_API_V1}/auth/me"
+        resp = self.client.session.get(
+            url, timeout=self.client.timeout, proxies=self.client.proxies
+        )
+        return self.client.process_response("GET", resp)
+
+    def get_transactions(self, account_id, limit=None, offset=None):
+        """
+        GET https://api.vobiz.ai/api/v1/account/{account_id}/transactions
+        """
+        url = f"{VOBIZ_API_V1}/account/{account_id}/transactions"
+        params = {}
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+        resp = self.client.session.get(
+            url, params=params, timeout=self.client.timeout, proxies=self.client.proxies
+        )
+        return self.client.process_response("GET", resp)
+
+    def get_balance(self, account_id, currency):
+        """
+        GET https://api.vobiz.ai/api/v1/account/{account_id}/balance/{currency}
+        """
+        url = f"{VOBIZ_API_V1}/account/{account_id}/balance/{currency}"
+        resp = self.client.session.get(
+            url, timeout=self.client.timeout, proxies=self.client.proxies
+        )
+        return self.client.process_response("GET", resp)
+
+    def get_concurrency(self, account_id):
+        """
+        GET https://api.vobiz.ai/api/v1/account/{account_id}/concurrency
+        """
+        url = f"{VOBIZ_API_V1}/account/{account_id}/concurrency"
+        resp = self.client.session.get(
+            url, timeout=self.client.timeout, proxies=self.client.proxies
+        )
+        return self.client.process_response("GET", resp)
+

vobiz/resources/applications.py

@@ -0,0 +1,138 @@
+from typing import Any, Dict, Optional
+
+VOBIZ_API_V1 = "https://api.vobiz.ai/api/v1"
+
+
+class Applications:
+    """
+    Vobiz Applications resource.
+
+    All endpoints are scoped to the authenticated account.
+    """
+
+    def __init__(self, client):
+        self.client = client
+
+    @property
+    def _account_id(self) -> str:
+        # For Vobiz, we treat the RestClient auth_id as the account_id
+        return self.client.auth_id
+
+    def create(
+        self,
+        name: str,
+        answer_url: str,
+        answer_method: str = "POST",
+        hangup_url: Optional[str] = None,
+        hangup_method: str = "POST",
+        fallback_answer_url: Optional[str] = None,
+        fallback_method: str = "POST",
+        application_type: Optional[str] = None,
+        **extra: Any,
+    ):
+        """
+        POST /api/v1/Account/{account_id}/Application/
+        """
+        url = f"{VOBIZ_API_V1}/Account/{self._account_id}/Application/"
+        body: Dict[str, Any] = {
+            "name": name,
+            "answer_url": answer_url,
+            "answer_method": answer_method,
+            "hangup_method": hangup_method,
+        }
+        if hangup_url is not None:
+            body["hangup_url"] = hangup_url
+        if fallback_answer_url is not None:
+            body["fallback_answer_url"] = fallback_answer_url
+        if fallback_method is not None:
+            body["fallback_method"] = fallback_method
+        if application_type is not None:
+            body["application_type"] = application_type
+        # allow forward-compatible extra keys
+        body.update(extra)
+
+        resp = self.client.session.post(
+            url, json=body, timeout=self.client.timeout, proxies=self.client.proxies
+        )
+        return self.client.process_response("POST", resp)
+
+    def list(
+        self,
+        page: Optional[int] = None,
+        size: Optional[int] = None,
+        application_type: Optional[str] = None,
+    ):
+        """
+        GET /api/v1/Account/{account_id}/Application/
+        """
+        url = f"{VOBIZ_API_V1}/Account/{self._account_id}/Application/"
+        params: Dict[str, Any] = {}
+        if page is not None:
+            params["page"] = page
+        if size is not None:
+            params["size"] = size
+        if application_type is not None:
+            params["application_type"] = application_type
+
+        resp = self.client.session.get(
+            url, params=params, timeout=self.client.timeout, proxies=self.client.proxies
+        )
+        return self.client.process_response("GET", resp)
+
+    def get(self, application_id: str):
+        """
+        GET /api/v1/Account/{account_id}/Application/{application_id}
+        """
+        url = f"{VOBIZ_API_V1}/Account/{self._account_id}/Application/{application_id}"
+        resp = self.client.session.get(
+            url, timeout=self.client.timeout, proxies=self.client.proxies
+        )
+        return self.client.process_response("GET", resp)
+
+    def update(self, application_id: str, **params: Any):
+        """
+        POST /api/v1/Account/{account_id}/Application/{application_id}/
+        """
+        url = f"{VOBIZ_API_V1}/Account/{self._account_id}/Application/{application_id}/"
+        body: Dict[str, Any] = dict(params)
+        resp = self.client.session.post(
+            url, json=body, timeout=self.client.timeout, proxies=self.client.proxies
+        )
+        return self.client.process_response("POST", resp)
+
+    def delete(self, application_id: str):
+        """
+        DELETE /api/v1/Account/{account_id}/Application/{application_id}
+        """
+        url = f"{VOBIZ_API_V1}/Account/{self._account_id}/Application/{application_id}"
+        resp = self.client.session.delete(
+            url, timeout=self.client.timeout, proxies=self.client.proxies
+        )
+        return self.client.process_response("DELETE", resp)
+
+    def attach_number(self, number: str, application_id: str):
+        """
+        POST /api/v1/account/{account_id}/numbers/{number}/application
+
+        Attach a phone number to a voice application.
+        number: E.164 format, e.g. "+911234567890"
+        """
+        url = f"{VOBIZ_API_V1}/account/{self._account_id}/numbers/{number}/application"
+        body = {"application_id": application_id}
+        resp = self.client.session.post(
+            url, json=body, timeout=self.client.timeout, proxies=self.client.proxies
+        )
+        return self.client.process_response("POST", resp)
+
+    def detach_number(self, number: str):
+        """
+        DELETE /api/v1/account/{account_id}/numbers/{number}/application
+
+        Detach a phone number from its voice application.
+        number: E.164 format, e.g. "+911234567890"
+        """
+        url = f"{VOBIZ_API_V1}/account/{self._account_id}/numbers/{number}/application"
+        resp = self.client.session.delete(
+            url, timeout=self.client.timeout, proxies=self.client.proxies
+        )
+        return self.client.process_response("DELETE", resp)

vobiz/resources/calls_vobiz.py

@@ -0,0 +1,206 @@
+from typing import Any, Dict, Optional
+
+
+class Calls:
+    """
+    Vobiz Calls resource.
+
+    Uses the `/api/v1/account/{auth_id}/call/` endpoints for call control and
+    live/queued status listing, plus DTMF.
+    """
+
+    def __init__(self, client):
+        self.client = client
+
+    @property
+    def _account_id(self) -> str:
+        return self.client.auth_id
+
+    def create(self, from_: str, to_: str, answer_url: str, **params: Any):
+        """
+        POST /api/v1/Account/{auth_id}/Call/
+        """
+        body: Dict[str, Any] = {
+            "from": from_,
+            "to": to_,
+            "answer_url": answer_url,
+        }
+        body.update(params)
+        return self.client.request("POST", ("Call",), data=body)
+
+    def transfer(self, call_uuid: str, **params: Any):
+        """
+        POST /api/v1/Account/{auth_id}/Call/{call_uuid}/
+        """
+        return self.client.request("POST", ("Call", call_uuid), data=dict(params))
+
+    def hangup(self, call_uuid: str):
+        """
+        DELETE /api/v1/Account/{auth_id}/Call/{call_uuid}/
+        """
+        return self.client.request("DELETE", ("Call", call_uuid))
+
+    def list(self, status: Optional[str] = None, **filters: Any):
+        """
+        GET /api/v1/Account/{auth_id}/Call/
+        """
+        params: Dict[str, Any] = dict(filters)
+        if status is not None:
+            params["status"] = status
+        return self.client.request(
+            "GET",
+            ("Call",),
+            data=params,
+        )
+
+    def get(self, call_uuid: str, status: Optional[str] = None):
+        """
+        GET /api/v1/Account/{auth_id}/Call/{call_uuid}/
+        """
+        params: Dict[str, Any] = {}
+        if status is not None:
+            params["status"] = status
+        return self.client.request("GET", ("Call", call_uuid), data=params)
+
+    def list_live(self):
+        return self.list(status="live")
+
+    def list_queued(self):
+        return self.list(status="queued")
+
+    def get_live(self, call_uuid: str):
+        return self.get(call_uuid, status="live")
+
+    def get_queued(self, call_uuid: str):
+        return self.get(call_uuid, status="queued")
+
+    def send_digits(self, call_uuid: str, digits: str, leg: str):
+        """
+        POST /api/v1/Account/{auth_id}/Call/{call_uuid}/DTMF/
+        """
+        body: Dict[str, Any] = {"digits": digits, "leg": leg}
+        return self.client.request("POST", ("Call", call_uuid, "DTMF"), data=body)
+
+    # ── Recording ──────────────────────────────────────────────────────────────
+
+    def start_recording(
+        self,
+        call_uuid: str,
+        time_limit: Optional[int] = None,
+        file_format: Optional[str] = None,
+        callback_url: Optional[str] = None,
+        callback_method: Optional[str] = None,
+        **params: Any,
+    ):
+        """
+        POST /api/v1/Account/{auth_id}/Call/{call_uuid}/Record/
+
+        Start recording an active call.
+        """
+        body: Dict[str, Any] = {}
+        if time_limit is not None:
+            body["time_limit"] = time_limit
+        if file_format is not None:
+            body["file_format"] = file_format
+        if callback_url is not None:
+            body["callback_url"] = callback_url
+        if callback_method is not None:
+            body["callback_method"] = callback_method
+        body.update(params)
+        return self.client.request("POST", ("Call", call_uuid, "Record"), data=body)
+
+    def stop_recording(self, call_uuid: str, url: Optional[str] = None):
+        """
+        DELETE /api/v1/Account/{auth_id}/Call/{call_uuid}/Record/
+
+        Stop recording on an active call.
+        If url is provided, stops only that specific recording.
+        If omitted, stops all recordings on the call.
+        """
+        body: Dict[str, Any] = {}
+        if url is not None:
+            body["URL"] = url
+        return self.client.request("DELETE", ("Call", call_uuid, "Record"), data=body)
+
+    # ── Play Audio ─────────────────────────────────────────────────────────────
+
+    def play_audio(
+        self,
+        call_uuid: str,
+        urls: list,
+        length: Optional[int] = None,
+        legs: Optional[str] = None,
+        loop: Optional[bool] = None,
+        mix: Optional[bool] = None,
+        **params: Any,
+    ):
+        """
+        POST /api/v1/Account/{auth_id}/Call/{call_uuid}/Play/
+
+        Play one or more audio files during an active call.
+        urls: list of HTTPS URLs to audio files (mp3/wav).
+        legs: "aleg", "bleg", or "both" (default "aleg").
+        """
+        body: Dict[str, Any] = {"urls": urls}
+        if length is not None:
+            body["length"] = length
+        if legs is not None:
+            body["legs"] = legs
+        if loop is not None:
+            body["loop"] = loop
+        if mix is not None:
+            body["mix"] = mix
+        body.update(params)
+        return self.client.request("POST", ("Call", call_uuid, "Play"), data=body)
+
+    def stop_audio(self, call_uuid: str):
+        """
+        DELETE /api/v1/Account/{auth_id}/Call/{call_uuid}/Play/
+
+        Stop audio playback on an active call.
+        """
+        return self.client.request("DELETE", ("Call", call_uuid, "Play"), data={})
+
+    # ── Speak Text (TTS) ───────────────────────────────────────────────────────
+
+    def speak_text(
+        self,
+        call_uuid: str,
+        text: str,
+        voice: Optional[str] = None,
+        language: Optional[str] = None,
+        legs: Optional[str] = None,
+        loop: Optional[bool] = None,
+        mix: Optional[bool] = None,
+        **params: Any,
+    ):
+        """
+        POST /api/v1/Account/{auth_id}/Call/{call_uuid}/Speak/
+
+        Convert text to speech and play it during an active call.
+        voice: "WOMAN" or "MAN" (default "WOMAN").
+        language: BCP-47 language code, e.g. "en-US" (default).
+        legs: "aleg", "bleg", or "both".
+        """
+        body: Dict[str, Any] = {"text": text}
+        if voice is not None:
+            body["voice"] = voice
+        if language is not None:
+            body["language"] = language
+        if legs is not None:
+            body["legs"] = legs
+        if loop is not None:
+            body["loop"] = loop
+        if mix is not None:
+            body["mix"] = mix
+        body.update(params)
+        return self.client.request("POST", ("Call", call_uuid, "Speak"), data=body)
+
+    def stop_speak(self, call_uuid: str):
+        """
+        DELETE /api/v1/Account/{auth_id}/Call/{call_uuid}/Speak/
+
+        Stop text-to-speech currently playing on an active call.
+        """
+        return self.client.request("DELETE", ("Call", call_uuid, "Speak"), data={})
+