Add Users (#269)

* add users api and tests

* updated README

* updated changelog

* Bump version: 3.7.1 → 3.8.0

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 3.7.1
+current_version = 3.8.0
 commit = True
 tag = False
 

CHANGES.md

@@ -1,3 +1,6 @@
+# 3.8.0
+- Adding support for the [Users component of the Vonage Application API](https://developer.vonage.com/en/api/application.v2#User)
+
 # 3.7.1
 - Fixing dependency version to a specific major version
 

README.md

@@ -27,6 +27,7 @@ need a Vonage account. Sign up [for free at vonage.com][signup].
 - [Pricing API](#pricing-api)
 - [Managing Secrets](#managing-secrets)
 - [Application API](#application-api)
+- [Users API](#users-api)
 - [Validating Webhook Signatures](#validate-webhook-signatures)
 - [JWT Parameters](#jwt-parameters)
 - [Overriding API Attributes](#overriding-api-attributes)
@@ -1082,6 +1083,42 @@ response = client.application.delete_application(uuid)
 
 Docs: [https://developer.nexmo.com/api/application.v2#deleteApplication](https://developer.nexmo.com/api/application.v2#deleteApplication?utm_source=DEV_REL&utm_medium=github&utm_campaign=python-client-library#destroy-an-application)
 
+
+## Users API
+
+These API methods are part of the [Application (v2) API](https://developer.vonage.com/en/application/overview) but are a in separate module in the SDK. [See the API reference for more details](https://developer.vonage.com/en/api/application.v2#User).
+
+### List all Users
+
+```python
+client.users.list_users()
+```
+
+### Create a new user
+
+```python
+client.users.create_user() # Default values generated
+client.users.create_user(params={...}) # Specify custom values
+```
+
+### Get detailed information about a user
+
+```python
+client.users.get_user('USER_ID')
+```
+
+### Update user details
+
+```python
+client.users.update_user('USER_ID', params={...})
+```
+
+### Delete a user
+
+```python
+client.users.delete_user('USER_ID')
+```
+
 ## Validate webhook signatures
 
 ```python

setup.py

@@ -9,7 +9,7 @@
 
 setup(
     name="vonage",
-    version="3.7.1",
+    version="3.8.0",
     description="Vonage Server SDK for Python",
     long_description=long_description,
     long_description_content_type="text/markdown",

src/vonage/__init__.py

@@ -1,4 +1,4 @@
 from .client import *
 from .ncco_builder.ncco import *
 
-__version__ = "3.7.1"
+__version__ = "3.8.0"

src/vonage/client.py

@@ -13,6 +13,7 @@
 from .short_codes import ShortCodes
 from .sms import Sms
 from .subaccounts import Subaccounts
+from .users import Users
 from .ussd import Ussd
 from .voice import Voice
 from .verify import Verify
@@ -122,6 +123,7 @@ def __init__(
         self.short_codes = ShortCodes(self)
         self.sms = Sms(self)
         self.subaccounts = Subaccounts(self)
+        self.users = Users(self)
         self.ussd = Ussd(self)
         self.verify = Verify(self)
         self.verify2 = Verify2(self)

src/vonage/errors.py

@@ -50,3 +50,7 @@ class SubaccountsError(ClientError):
 
 class ProactiveConnectError(ClientError):
     """An error relating to the Proactive Connect API."""
+
+
+class UsersError(ClientError):
+    """An error relating to the Users API."""

src/vonage/users.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from vonage import Client
+
+from .errors import UsersError
+from ._internal import set_auth_type
+
+
+class Users:
+    """Class containing methods for user management as part of the Application API."""
+
+    def __init__(self, client: Client):
+        self._client = client
+        self._auth_type = set_auth_type(self._client)
+
+    def list_users(
+        self,
+        page_size: int = None,
+        order: str = 'asc',
+        cursor: str = None,
+        name: str = None,
+    ):
+        """
+        Lists the name and user id of all users associated with the account.
+        For complete information on a user, call Users.get_user, passing in the user id.
+        """
+
+        if order.lower() not in ('asc', 'desc'):
+            raise UsersError(
+                'Invalid order parameter. Must be one of: "asc", "desc", "ASC", "DESC".'
+            )
+
+        params = {'page_size': page_size, 'order': order.lower(), 'cursor': cursor, 'name': name}
+        return self._client.get(
+            self._client.api_host(),
+            '/v1/users',
+            params,
+            auth_type=self._auth_type,
+        )
+
+    def create_user(self, params: dict = None):
+        self._client.headers['Content-Type'] = 'application/json'
+        return self._client.post(
+            self._client.api_host(),
+            '/v1/users',
+            params,
+            auth_type=self._auth_type,
+        )
+
+    def get_user(self, user_id: str):
+        return self._client.get(
+            self._client.api_host(),
+            f'/v1/users/{user_id}',
+            auth_type=self._auth_type,
+        )
+
+    def update_user(self, user_id: str, params: dict):
+        return self._client.patch(
+            self._client.api_host(),
+            f'/v1/users/{user_id}',
+            params,
+            auth_type=self._auth_type,
+        )
+
+    def delete_user(self, user_id: str):
+        return self._client.delete(
+            self._client.api_host(),
+            f'/v1/users/{user_id}',
+            auth_type=self._auth_type,
+        )

tests/data/users/invalid_content_type.json

@@ -0,0 +1,13 @@
+{
+    "title": "Bad request.",
+    "type": "https://developer.nexmo.com/api/conversation#http:error:validation-fail",
+    "code": "http:error:validation-fail",
+    "detail": "Invalid Content-Type.",
+    "instance": "9d0e245d-fac0-450e-811f-52343041df61",
+    "invalid_parameters": [
+        {
+            "name": "content-type",
+            "reason": "content-type \"application/octet-stream\" is not supported. Supported versions are [application/json]"
+        }
+    ]
+}

tests/data/users/list_users_400.json

@@ -0,0 +1,13 @@
+{
+    "title": "Bad request.",
+    "type": "https://developer.nexmo.com/api/conversation#http:error:validation-fail",
+    "code": "http:error:validation-fail",
+    "detail": "Input validation failure.",
+    "instance": "04ee4d32-78c9-4acf-bdc1-b7d1fa860c92",
+    "invalid_parameters": [
+        {
+            "name": "page_size",
+            "reason": "\"page_size\" must be a number"
+        }
+    ]
+}

tests/data/users/list_users_404.json

@@ -0,0 +1,7 @@
+{
+    "title": "Not found.",
+    "type": "https://developer.nexmo.com/api/conversation#user:error:not-found",
+    "code": "user:error:not-found",
+    "detail": "User does not exist, or you do not have access.",
+    "instance": "29c78817-eeb9-4de0-b2f9-a5ca816bc907"
+}

tests/data/users/list_users_500.json

@@ -0,0 +1,7 @@
+{
+    "title": "Internal Error.",
+    "type": "https://developer.nexmo.com/api/conversation#system:error:internal-error",
+    "code": "system:error:internal-error",
+    "detail": "Something went wrong.",
+    "instance": "00a5916655d650e920ccf0daf40ef4ee"
+}

tests/data/users/list_users_basic.json

@@ -0,0 +1,43 @@
+{
+    "page_size": 10,
+    "_embedded": {
+        "users": [
+            {
+                "id": "USR-2af4d3c5-ec49-4c4a-b74c-ec13ab560af8",
+                "name": "NAM-6dd4ea1f-3841-47cb-a3d3-e271f5c1e33c",
+                "_links": {
+                    "self": {
+                        "href": "https://api-us-3.vonage.com/v1/users/USR-2af4d3c5-ec49-4c4a-b74c-ec13ab560af8"
+                    }
+                }
+            },
+            {
+                "id": "USR-d3cc6a55-aa7b-4916-8244-2fedb554afd5",
+                "name": "NAM-ecb938f2-13e0-40c1-9d3b-b16ebb4ef3d1",
+                "_links": {
+                    "self": {
+                        "href": "https://api-us-3.vonage.com/v1/users/USR-d3cc6a55-aa7b-4916-8244-2fedb554afd5"
+                    }
+                }
+            },
+            {
+                "id": "USR-5ab17d58-b8b3-427d-ac42-c31dab7ef422",
+                "name": "my_user_name",
+                "display_name": "My User Name",
+                "_links": {
+                    "self": {
+                        "href": "https://api-us-3.vonage.com/v1/users/USR-5ab17d58-b8b3-427d-ac42-c31dab7ef422"
+                    }
+                }
+            }
+        ]
+    },
+    "_links": {
+        "first": {
+            "href": "https://api-us-3.vonage.com/v1/users?order=asc&page_size=10"
+        },
+        "self": {
+            "href": "https://api-us-3.vonage.com/v1/users?order=asc&page_size=10&cursor=QAuYbTXFALruTxAIRAKiHvdCAqJQjTuYkDNhN9PYWcDajgUTgd9lQPo%3D"
+        }
+    }
+}

tests/data/users/list_users_options.json

@@ -0,0 +1,37 @@
+{
+    "page_size": 2,
+    "_embedded": {
+        "users": [
+            {
+                "id": "USR-5ab17d58-b8b3-427d-ac42-c31dab7ef422",
+                "name": "my_user_name",
+                "display_name": "My User Name",
+                "_links": {
+                    "self": {
+                        "href": "https://api-us-3.vonage.com/v1/users/USR-5ab17d58-b8b3-427d-ac42-c31dab7ef422"
+                    }
+                }
+            },
+            {
+                "id": "USR-d3cc6a55-aa7b-4916-8244-2fedb554afd5",
+                "name": "NAM-ecb938f2-13e0-40c1-9d3b-b16ebb4ef3d1",
+                "_links": {
+                    "self": {
+                        "href": "https://api-us-3.vonage.com/v1/users/USR-d3cc6a55-aa7b-4916-8244-2fedb554afd5"
+                    }
+                }
+            }
+        ]
+    },
+    "_links": {
+        "first": {
+            "href": "https://api-us-3.vonage.com/v1/users?order=desc&page_size=2"
+        },
+        "self": {
+            "href": "https://api-us-3.vonage.com/v1/users?order=desc&page_size=2&cursor=Tw2iIH8ISR4SuJRJUrK9xC78rhfI10HHRKOZ20zBN9A8SDiczcOqBj8%3D"
+        },
+        "next": {
+            "href": "https://api-us-3.vonage.com/v1/users?order=desc&page_size=2&cursor=FBWj1Oxid%2FVkxP6BT%2FCwMZZ2C0uOby0QXCrebkNoNo4A3PU%2FQTOOoD%2BWHib6ewsVLygsQBJy7di8HI9m30A3ujVuv1578w4Lqitgbv6CAnxdzPMeLCcAxNYWxl8%3D"
+        }
+    }
+}

tests/data/users/rate_limit.json

@@ -0,0 +1,7 @@
+{
+    "title": "Too Many Requests.",
+    "type": "https://developer.nexmo.com/api/conversation#http:error:too-many-request",
+    "code": "http:error:too-many-request",
+    "detail": "You have exceeded your request limit. You can try again shortly.",
+    "instance": "00a5916655d650e920ccf0daf40ef4ee"
+}

tests/data/users/user_400.json

@@ -0,0 +1,13 @@
+{
+    "title": "Bad request.",
+    "type": "https://developer.nexmo.com/api/conversation#http:error:validation-fail",
+    "code": "http:error:validation-fail",
+    "detail": "Input validation failure.",
+    "instance": "00a5916655d650e920ccf0daf40ef4ee",
+    "invalid_parameters": [
+        {
+            "name": "name",
+            "reason": "\"name\" must be a string"
+        }
+    ]
+}

tests/data/users/user_404.json

@@ -0,0 +1,7 @@
+{
+    "title": "Not found.",
+    "type": "https://developer.nexmo.com/api/conversation#user:error:not-found",
+    "code": "user:error:not-found",
+    "detail": "User does not exist, or you do not have access.",
+    "instance": "9b3b0ea8-987a-4117-b75a-8425e04910c4"
+}

tests/data/users/user_basic.json

@@ -0,0 +1,13 @@
+{
+    "id": "USR-d3cc6a55-aa7b-4916-8244-2fedb554afd5",
+    "name": "NAM-ecb938f2-13e0-40c1-9d3b-b16ebb4ef3d1",
+    "properties": {
+        "custom_data": {}
+    },
+    "_links": {
+        "self": {
+            "href": "https://api-us-3.vonage.com/v1/users/USR-d3cc6a55-aa7b-4916-8244-2fedb554afd5"
+        }
+    },
+    "channels": {}
+}