vobiz-python 0.1.0__py3-none-any.whl

vobiz/resources/sip_trunks.py

@@ -0,0 +1,99 @@
+from typing import Any, Dict, Optional
+
+VOBIZ_API_V1 = "https://api.vobiz.ai/api/v1"
+
+
+class SipTrunks:
+    """
+    Vobiz SIP Trunks resource.
+
+    Uses the `/api/v1/account/{account_id}/trunks/...` paths described in
+    the Vobiz SIP trunks documentation.
+    """
+
+    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,
+        inbound_uri: Optional[str] = None,
+        outbound_uri: Optional[str] = None,
+        **extra: Any,
+    ):
+        """
+        POST /api/v1/account/{account_id}/trunks
+        """
+        url = f"{VOBIZ_API_V1}/account/{self._account_id}/trunks"
+        body: Dict[str, Any] = {"name": name}
+        if inbound_uri is not None:
+            body["inbound_uri"] = inbound_uri
+        if outbound_uri is not None:
+            body["outbound_uri"] = outbound_uri
+        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,
+        **filters: Any,
+    ):
+        """
+        GET /api/v1/account/{account_id}/trunks
+        """
+        url = f"{VOBIZ_API_V1}/account/{self._account_id}/trunks"
+        params: Dict[str, Any] = {}
+        if page is not None:
+            params["page"] = page
+        if size is not None:
+            params["size"] = size
+        params.update(filters)
+
+        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, trunk_id: str):
+        """
+        GET /api/v1/account/{account_id}/trunks/{trunk_id}
+        """
+        url = f"{VOBIZ_API_V1}/account/{self._account_id}/trunks/{trunk_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, trunk_id: str, **params: Any):
+        """
+        PUT /api/v1/account/{account_id}/trunks/{trunk_id}
+        """
+        url = f"{VOBIZ_API_V1}/account/{self._account_id}/trunks/{trunk_id}"
+        body: Dict[str, Any] = dict(params)
+        resp = self.client.session.put(
+            url, json=body, timeout=self.client.timeout, proxies=self.client.proxies
+        )
+        return self.client.process_response("PUT", resp)
+
+    def delete(self, trunk_id: str):
+        """
+        DELETE /api/v1/account/{account_id}/trunks/{trunk_id}
+
+        Permanently delete a SIP trunk and its associated resources.
+        """
+        url = f"{VOBIZ_API_V1}/account/{self._account_id}/trunks/{trunk_id}"
+        resp = self.client.session.delete(
+            url, timeout=self.client.timeout, proxies=self.client.proxies
+        )
+        return self.client.process_response("DELETE", resp)
+

vobiz/resources/subaccounts.py

@@ -0,0 +1,101 @@
+from typing import Any, Dict, Optional
+
+VOBIZ_API_V1 = "https://api.vobiz.ai/api/v1"
+
+
+class Subaccounts:
+    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,
+        email: str,
+        rate_limit: int,
+        permissions: Any,
+        password: str,
+        phone: Optional[str] = None,
+        description: Optional[str] = None,
+        enabled: bool = True,
+    ):
+        """
+        POST /api/v1/accounts/{account_id}/sub-accounts/
+        """
+        url = f"{VOBIZ_API_V1}/accounts/{self._account_id}/sub-accounts/"
+        body: Dict[str, Any] = {
+            "name": name,
+            "email": email,
+            "rate_limit": rate_limit,
+            "permissions": permissions,
+            "password": password,
+            "enabled": enabled,
+        }
+        if phone is not None:
+            body["phone"] = phone
+        if description is not None:
+            body["description"] = description
+
+        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,
+        active_only: Optional[bool] = None,
+    ):
+        """
+        GET /api/v1/accounts/{account_id}/sub-accounts/
+        """
+        url = f"{VOBIZ_API_V1}/accounts/{self._account_id}/sub-accounts/"
+        params: Dict[str, Any] = {}
+        if page is not None:
+            params["page"] = page
+        if size is not None:
+            params["size"] = size
+        if active_only is not None:
+            params["active_only"] = active_only
+
+        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, sub_account_id: str):
+        """
+        GET /api/v1/accounts/{account_id}/sub-accounts/{sub_account_id}
+        """
+        url = f"{VOBIZ_API_V1}/accounts/{self._account_id}/sub-accounts/{sub_account_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, sub_account_id: str, **params: Any):
+        """
+        PUT /api/v1/accounts/{account_id}/sub-accounts/{sub_account_id}
+        """
+        url = f"{VOBIZ_API_V1}/accounts/{self._account_id}/sub-accounts/{sub_account_id}"
+        body: Dict[str, Any] = dict(params)
+        resp = self.client.session.put(
+            url, json=body, timeout=self.client.timeout, proxies=self.client.proxies
+        )
+        return self.client.process_response("PUT", resp)
+
+    def delete(self, sub_account_id: str):
+        """
+        DELETE /api/v1/accounts/{account_id}/sub-accounts/{sub_account_id}
+        """
+        url = f"{VOBIZ_API_V1}/accounts/{self._account_id}/sub-accounts/{sub_account_id}"
+        resp = self.client.session.delete(
+            url, timeout=self.client.timeout, proxies=self.client.proxies
+        )
+        return self.client.process_response("DELETE", resp)
+

vobiz/rest/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+from .client import Client

vobiz/rest/client.py

@@ -0,0 +1,277 @@
+# -*- coding: utf-8 -*-
+"""
+Core client, used for all API requests.
+"""
+
+import os
+import platform
+from collections import namedtuple
+
+from dotenv import load_dotenv
+load_dotenv()
+
+from vobiz.base import ResponseObject
+from vobiz.exceptions import (
+    AuthenticationError,
+    InvalidRequestError,
+    VobizRestError,
+    VobizServerError,
+    GeoPermissionError,
+    ResourceNotFoundError,
+    ValidationError,
+    ForbiddenError,
+)
+from vobiz.resources import (
+    Calls,
+    Accounts,
+    Subaccounts,
+    Applications,
+    Recordings,
+    CDRs,
+    PhoneNumbers,
+    Endpoints,
+    SipTrunks,
+    Credentials,
+    IpAccessControlLists,
+    OriginationUris,
+)
+from vobiz.version import __version__
+from requests import Request, Session
+
+AuthenticationCredentials = namedtuple("AuthenticationCredentials", "auth_id auth_token")
+
+VOBIZ_API = "https://api.vobiz.ai/api"
+VOBIZ_API_BASE_URI = "/".join([VOBIZ_API, "v1/Account"])
+
+GEO_PERMISSION_ENDPOINTS = ["/Call/"]
+
+
+def get_user_agent():
+    return "vobiz-python/%s (Python: %s)" % (__version__, platform.python_version())
+
+
+def fetch_credentials(auth_id, auth_token):
+    """Fetch credentials from arguments"""
+
+    if not (auth_id and auth_token):
+        try:
+            auth_id = os.environ["VOBIZ_AUTH_ID"]
+            auth_token = os.environ["VOBIZ_AUTH_TOKEN"]
+        except KeyError:
+            raise AuthenticationError(
+                "The Vobiz Python SDK could not find your auth credentials."
+            )
+
+    if not isinstance(auth_id, str) or not auth_id:
+        raise AuthenticationError("Invalid auth_id supplied: %s" % auth_id)
+
+    if not isinstance(auth_token, str) or not auth_token:
+        raise AuthenticationError("Invalid auth_token supplied.")
+
+    return AuthenticationCredentials(auth_id=auth_id, auth_token=auth_token)
+
+
+class Client(object):
+    def __init__(self, auth_id=None, auth_token=None, proxies=None, timeout=5):
+        """
+        The Vobiz API client.
+
+        Deals with all the API requests to be made.
+        """
+
+        self.base_uri = VOBIZ_API_BASE_URI
+        self.session = Session()
+        self.session.headers.update(
+            {
+                "User-Agent": get_user_agent(),
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            }
+        )
+        creds = fetch_credentials(auth_id, auth_token)
+        self.auth_id = creds.auth_id
+        self.auth_token = creds.auth_token
+        self.session.headers.update(
+            {"X-Auth-ID": self.auth_id, "X-Auth-Token": self.auth_token}
+        )
+        self.multipart_session = Session()
+        self.multipart_session.headers.update(
+            {
+                "User-Agent": get_user_agent(),
+                "Cache-Control": "no-cache",
+            }
+        )
+        self.multipart_session.headers.update(
+            {"X-Auth-ID": self.auth_id, "X-Auth-Token": self.auth_token}
+        )
+        self.proxies = proxies
+        self.timeout = timeout
+        self.calls = Calls(self)
+        self.accounts = Accounts(self)
+        self.subaccounts = Subaccounts(self)
+        self.applications = Applications(self)
+        self.recordings = Recordings(self)
+        self.cdrs = CDRs(self)
+        self.phone_numbers = PhoneNumbers(self)
+        self.endpoints = Endpoints(self)
+        self.sip_trunks = SipTrunks(self)
+        self.credentials = Credentials(self)
+        self.ip_access_control_lists = IpAccessControlLists(self)
+        self.origination_uris = OriginationUris(self)
+
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.session.close()
+        self.multipart_session.close()
+
+    def process_response(self,
+                         method,
+                         response,
+                         response_type=None,
+                         objects_type=None):
+        """Processes the API response based on the status codes and method used
+        to access the API
+        """
+        try:
+            response_json = response.json(
+                object_hook=lambda x: ResponseObject(x) if isinstance(x, dict) else x)
+            if response_type:
+                r = response_type(self, response_json.__dict__)
+                response_json = r
+
+            if 'objects' in response_json and objects_type:
+                response_json.objects = [
+                    objects_type(self, obj.__dict__)
+                    for obj in response_json.objects
+                ]
+        except ValueError:
+            response_json = None
+
+        if response.status_code == 400:
+            if response_json is not None and 'error' in response_json:
+                raise ValidationError(response_json.error)
+            raise ValidationError(
+                'A parameter is missing or is invalid while accessing resource'
+                'at: {url}'.format(url=response.url))
+
+        if response.status_code == 401:
+            if response_json and 'error' in response_json:
+                raise AuthenticationError(response_json.error)
+            raise AuthenticationError(
+                'Failed to authenticate while accessing resource at: '
+                '{url}'.format(url=response.url))
+
+        if response.status_code == 403:
+            error = ForbiddenError
+            if method == "POST" and any(response.url.endswith(endpoint) for endpoint in GEO_PERMISSION_ENDPOINTS):
+                error = GeoPermissionError
+            if response_json and 'error' in response_json:
+                raise error(response_json.error)
+            raise error(
+                'Request Failed : '
+                '{url}'.format(url=response.url))
+
+        if response.status_code == 404:
+            if response_json and 'error' in response_json:
+                raise ResourceNotFoundError(response_json.error)
+            raise ResourceNotFoundError(
+                'Resource not found at: {url}'.format(url=response.url))
+
+        if response.status_code == 405:
+            if response_json and 'error' in response_json:
+                raise InvalidRequestError(response_json.error)
+            raise InvalidRequestError(
+                'HTTP method "{method}" not allowed to access resource at: '
+                '{url}'.format(method=method, url=response.url))
+
+        if response.status_code == 409:
+            if response_json and 'error' in response_json:
+                raise InvalidRequestError(response_json.error)
+            raise InvalidRequestError(
+                'Conflict: '
+                '{url}'.format(url=response.url))
+
+        if response.status_code == 422:
+            if response_json and 'error' in response_json:
+                raise InvalidRequestError(response_json.error)
+            raise InvalidRequestError(
+                'Unprocessable Entity: '
+                '{url}'.format(url=response.url))
+
+        if response.status_code == 500:
+            if response_json and 'error' in response_json:
+                raise VobizServerError(response_json.error)
+            raise VobizServerError(
+                'A server error occurred while accessing resource at: '
+                '{url}'.format(url=response.url))
+
+        if method == 'DELETE':
+            if response.status_code not in [200, 202, 204]:
+                raise VobizRestError('Resource at {url} could not be '
+                                     'deleted'.format(url=response.url))
+
+        elif response.status_code not in [200, 201, 202, 204, 206, 207]:
+            raise VobizRestError(
+                'Received status code {status_code} for the HTTP method '
+                '"{method}"'.format(
+                    status_code=response.status_code, method=method))
+
+        return response_json
+
+    def create_request(self, method, path=None, data=None, **kwargs):
+        path = path or []
+        url = '/'.join([self.base_uri, self.auth_id] + list([str(p) for p in path])) + '/'
+        req = Request(
+            method,
+            url,
+            **({'params': data} if method == 'GET' else {'json': data}),
+        )
+        return self.session.prepare_request(req)
+
+    def create_multipart_request(self,
+                                 method,
+                                 path=None,
+                                 data=None,
+                                 files=None):
+        path = path or []
+
+        data_args = {}
+        if method == 'GET':
+            data_args['params'] = data
+        else:
+            data_args['data'] = data
+            if files:
+                data_args['files'] = files
+        url = '/'.join([self.base_uri, self.auth_id] + list([str(p) for p in path])) + '/'
+        req = Request(method, url, **data_args)
+        return self.multipart_session.prepare_request(req)
+
+    def send_request(self, request, **kwargs):
+        if 'session' in kwargs:
+            session = kwargs['session']
+            del kwargs['session']
+        else:
+            session = self.session
+        return session.send(
+            request, proxies=self.proxies, timeout=self.timeout, **kwargs)
+
+    def request(self,
+                method,
+                path=None,
+                data=None,
+                response_type=None,
+                objects_type=None,
+                files=None,
+                **kwargs):
+        if files is not None:
+            req = self.create_multipart_request(method, path, data, files)
+            session = self.multipart_session
+        else:
+            req = self.create_request(method, path, data)
+            session = self.session
+        kwargs['session'] = session
+        res = self.send_request(req, **kwargs)
+        return self.process_response(method, res, response_type, objects_type)

vobiz/utils/__init__.py

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+import inspect
+import re
+from datetime import datetime
+
+from hmac import new as hnew
+from hashlib import sha256
+from urllib.parse import urlparse, urlunparse
+from base64 import encodebytes as base64_encode
+from inspect import getfullargspec as getargspec
+
+from .signature_v3 import validate_v3_signature
+
+
+def validate_signature(uri, nonce, signature, auth_token=''):
+    """
+    Validates requests made by Vobiz to your servers.
+
+    :param uri: Your server URL
+    :param nonce: X-Vobiz-Signature-V2-Nonce
+    :param signature: X-Vobiz-Signature-V2 header
+    :param auth_token: Vobiz Auth token
+    :return: True if the request matches signature, False otherwise
+    """
+
+    auth_token = bytes(auth_token.encode('utf-8'))
+    nonce = bytes(nonce.encode('utf-8'))
+    signature = bytes(signature.encode('utf-8'))
+
+    parsed_uri = urlparse(uri.encode('utf-8'))
+    base_url = urlunparse((parsed_uri.scheme.decode('utf-8'),
+                           parsed_uri.netloc.decode('utf-8'),
+                           parsed_uri.path.decode('utf-8'), '', '',
+                           '')).encode('utf-8')
+
+    return base64_encode(hnew(auth_token, base_url + nonce, sha256)
+                         .digest()).strip() == signature
+
+
+def is_valid_time_comparison(time):
+    if isinstance(time, datetime):
+        return True
+    return False
+
+
+def is_valid_subaccount(subaccount):
+    subaccount_string = str(subaccount)
+    if len(subaccount_string) == 20 and subaccount_string[:2] == 'SA':
+        return True
+    return False
+
+
+def is_valid_mainaccount(mainaccount):
+    mainaccount_string = str(mainaccount)
+    if len(mainaccount_string) == 20 and mainaccount_string[:2] == 'MA':
+        return True
+    return False
+
+
+def to_param_dict(func, vals, exclude_none=True, func_args_check=True):
+    args = getargspec(func)[0]
+    arg_names = list(args)
+    # The bit of regex magic below is for arguments that are keywords in
+    # Python, like from. These can't be used directly, so our convention is to
+    # add "_" suffixes to them. This strips them out.
+    pd = {
+        re.sub(r'^(.*)_+$', r'\1', key): value
+        for key, value in vals.items()
+        if key != 'self' and (key in arg_names or func_args_check == False) and (
+            value is not None or exclude_none is False)
+    }
+    return pd

vobiz/utils/interactive.py

@@ -0,0 +1,50 @@
+class Header:
+    def __init__(self, type=None, text=None, media=None):
+        self.type = type
+        self.text = text
+        self.media = media
+
+
+class Body:
+    def __init__(self, text=None):
+        self.text = text
+
+
+class Footer:
+    def __init__(self, text=None):
+        self.text = text
+
+
+class Row:
+    def __init__(self, id=None, title=None, description=None):
+        self.id = id
+        self.title = title
+        self.description = description
+
+
+class Section:
+    def __init__(self, title=None, rows=None):
+        self.title = title
+        self.rows = rows if rows is not None else []
+
+
+class Btn:
+    def __init__(self, id=None, title=None, cta_url=None):
+        self.id = id
+        self.title = title
+        self.cta_url = cta_url
+
+
+class Action:
+    def __init__(self, buttons=None, sections=None):
+        self.buttons = buttons if buttons is not None else []
+        self.sections = sections if sections is not None else []
+
+
+class Interactive:
+    def __init__(self, type=None, header=None, body=None, footer=None, action=None):
+        self.type = type
+        self.header = header
+        self.body = body
+        self.footer = footer
+        self.action = action

vobiz/utils/jwt.py

@@ -0,0 +1,97 @@
+from __future__ import absolute_import
+import jwt
+import time
+
+from vobiz.utils.validators import *
+
+
+class AccessToken:
+    """
+    Vobiz JWT AccessToken for SIP endpoint authentication.
+
+    Used to generate short-lived JWT tokens for WebRTC/SIP clients.
+    Not used for REST API authentication (which uses X-Auth-ID / X-Auth-Token headers).
+    """
+    auth_id = ''
+    username = ''
+    valid_from = 0
+    lifetime = 86400
+    key = ''
+    grants = {}
+    uid = 0
+
+    @validate_args(
+        auth_id=[is_account_id()],
+        auth_token=[optional(of_type(str))],
+        username=[all_of(
+            of_type(str),
+            check(lambda username: len(username) > 0, 'empty username')
+        )],
+        valid_from=[optional(of_type(int))],
+        lifetime=[
+            optional(
+                all_of(
+                    of_type(int),
+                    check(lambda lifetime: 180 <= lifetime <= 86400,
+                          '180 < lifetime <= 86400')))
+        ],
+        valid_till=[optional(of_type(int))],
+    )
+    def __init__(self,
+                 auth_id,
+                 auth_token,
+                 username,
+                 valid_from=None,
+                 lifetime=None,
+                 valid_till=None,
+                 uid=None):
+        self.auth_id = auth_id
+        self.username = username
+        if valid_from:
+            self.valid_from = int(valid_from)
+        else:
+            self.valid_from = int(time.time())
+        if lifetime:
+            self.lifetime = int(lifetime)
+            if valid_till is not None:
+                raise ValidationError("use either lifetime or valid_till")
+        elif valid_till:
+            self.lifetime = valid_till - self.valid_from
+            if self.lifetime < 0:
+                raise ValidationError(
+                    "validity expires %s seconds before it starts" %
+                    self.lifetime)
+            if self.lifetime < 180 or self.lifetime > 86400:
+                raise ValidationError(
+                    "validity of %s seconds is out of permitted range [180, 86400]" %
+                    self.lifetime)
+
+        self.key = auth_token
+
+        if uid:
+            self.uid = uid
+        else:
+            self.uid = "%s-%s" % (username, time.time())
+
+    @validate_args(
+        incoming=[optional(of_type_exact(bool))],
+        outgoing=[optional(of_type_exact(bool))],
+    )
+    def add_voice_grants(self, incoming=False, outgoing=False):
+        self.grants['voice'] = {
+            'incoming_allow': incoming,
+            'outgoing_allow': outgoing
+        }
+
+    def to_jwt(self):
+        headers = {'typ': 'JWT', 'cty': 'vobiz;v=1'}
+        algorithm = 'HS256'
+        claims = {
+            'jti': self.uid,
+            'iss': self.auth_id,
+            'sub': self.username,
+            'nbf': self.valid_from,
+            'exp': self.valid_from + self.lifetime,
+            'grants': self.grants
+        }
+        return jwt.encode(claims, self.key, algorithm=algorithm, headers=headers)