add account api, prepare for new releases

Author: maxkahan

account/README.md

@@ -1,77 +1,66 @@
-# Vonage Users Package
+# Vonage Account Package
 
-This package contains the code to use Vonage's Application API in Python.
+This package contains the code to use Vonage's Account API in Python.
 
-It includes methods for managing applications.
+It includes methods for managing Vonage accounts.
 
 ## Usage
 
 It is recommended to use this as part of the main `vonage` package. The examples below assume you've created an instance of the `vonage.Vonage` class called `vonage_client`.
 
-### List Applications
 
-With no custom options specified, this method will get the first 100 applications. It returns a tuple consisting of a list of `ApplicationData` objects and an int showing the page number of the next page of results.
+### Get Account Balance
 
 ```python
-from vonage_application import ListApplicationsFilter, ApplicationData
+balance = vonage_client.account.get_balance()
+print(balance)
+```
 
-applications, next_page = vonage_client.application.list_applications()
+### Top-Up Account
 
-# With options
-options = ListApplicationsFilter(page_size=3, page=2)
-applications, next_page = vonage_client.application.list_applications(options)
+```python
+response = vonage_client.account.top_up(trx='1234567890')
+print(response)
 ```
 
-### Create a New Application
+### Update the Default SMS Webhook
+
+This will return a Pydantic object (`SettingsResponse`) containing multiple settings for your account.
 
 ```python
-from vonage_application import ApplicationConfig
-
-app_data = vonage_client.application.create_application()
-
-# Create with custom options (can also be done with a dict)
-from vonage_application import ApplicationConfig, Keys, Voice, VoiceWebhooks
-voice = Voice(
-    webhooks=VoiceWebhooks(
-        event_url=VoiceUrl(
-            address='https://example.com/event',
-            http_method='POST',
-            connect_timeout=500,
-            socket_timeout=3000,
-        ),
-    ),
-    signed_callbacks=True,
+settings: SettingsResponse = vonage_client.account.update_default_sms_webhook(
+    mo_callback_url='https://example.com/inbound_sms_webhook',
+    dr_callback_url='https://example.com/delivery_receipt_webhook',
 )
-capabilities = Capabilities(voice=voice)
-keys = Keys(public_key='MY_PUBLIC_KEY')
-config = ApplicationConfig(
-    name='My Customised Application',
-    capabilities=capabilities,
-    keys=keys,
-)
-app_data = vonage_client.application.create_application(config)
+
+print(settings)
 ```
 
-### Get an Application
+### List Secrets Associated with the Account
 
 ```python
-app_data = client.application.get_application('MY_APP_ID')
-app_data_as_dict = app.model_dump(exclude_none=True)
+response = vonage_client.account.list_secrets()
+print(response)
 ```
 
-### Update an Application
-
-To update an application, pass config for the updated field(s) in an ApplicationConfig object
+### Create a New Account Secret
 
 ```python
-from vonage_application import ApplicationConfig, Keys, Voice, VoiceWebhooks
+secret = vonage_client.account.create_secret('Mytestsecret12345')
+print(secret)
+```
+
+### Get Information About One Secret
 
-config = ApplicationConfig(name='My Updated Application')
-app_data = vonage_client.application.update_application('MY_APP_ID', config)
+```python
+secret = vonage_client.account.get_secret(MY_SECRET_ID)
+print(secret)
 ```
 
-### Delete an Application
+### Revoke a Secret
+
+Note: it isn't possible to revoke all account secrets, there must always be one valid secret. Attempting to do so will give a 403 error.
 
 ```python
-vonage_client.applications.delete_application('MY_APP_ID')
-```
+client.account.revoke_secret(MY_SECRET_ID)
+```

account/pyproject.toml

@@ -6,7 +6,7 @@ readme = "README.md"
 authors = [{ name = "Vonage", email = "devrel@vonage.com" }]
 requires-python = ">=3.8"
 dependencies = [
-  "vonage-http-client>=1.3.1",
+  "vonage-http-client>=1.4.0",
   "vonage-utils>=1.1.2",
   "pydantic>=2.7.1",
 ]

account/src/vonage_account/__init__.py

@@ -1,3 +1,12 @@
 from .account import Account
+from .errors import InvalidSecretError
+from .responses import Balance, SettingsResponse, TopUpResponse, VonageApiSecret
 
-__all__ = ['Account']
+__all__ = [
+    'Account',
+    'Balance',
+    'InvalidSecretError',
+    'SettingsResponse',
+    'TopUpResponse',
+    'VonageApiSecret',
+]

account/src/vonage_account/account.py

@@ -1,8 +1,11 @@
+import re
+from typing import List
+
 from pydantic import validate_call
+from vonage_account.errors import InvalidSecretError
 from vonage_http_client.http_client import HttpClient
 
-from .requests import Balance
-from .responses import SettingsResponse, TopUpResponse
+from .responses import Balance, SettingsResponse, TopUpResponse, VonageApiSecret
 
 
 class Account:
@@ -21,7 +24,6 @@ def http_client(self) -> HttpClient:
         """
         return self._http_client
 
-    @validate_call
     def get_balance(self) -> Balance:
         """Get the balance of the account.
 
@@ -62,8 +64,8 @@ def top_up(self, trx: str) -> TopUpResponse:
     def update_default_sms_webhook(
         self, mo_callback_url: str = None, dr_callback_url: str = None
     ) -> SettingsResponse:
-        """Update the default SMS webhook URLs for the account.
-            In order to unset any default value, pass an empty string as the value.
+        """Update the default SMS webhook URLs for the account. In order to unset any default value,
+        pass an empty string as the value.
 
         Args:
             mo_callback_url (str, optional): The URL to which inbound SMS messages will be
@@ -89,10 +91,89 @@ def update_default_sms_webhook(
         )
         return SettingsResponse(**response)
 
-    def list_secrets(self) -> SecretList:
+    def list_secrets(self) -> List[VonageApiSecret]:
         """List all secrets associated with the account.
 
         Returns:
-            SecretList: List of Secret objects.
+            List[VonageApiSecret]: List of VonageApiSecret objects.
+        """
+        response = self._http_client.get(
+            self._http_client.api_host,
+            f'/accounts/{self._http_client.auth.api_key}/secrets',
+            auth_type=self._auth_type,
+        )
+        secrets = []
+        for element in response['_embedded']['secrets']:
+            secrets.append(VonageApiSecret(**element))
+
+        return secrets
+
+    @validate_call
+    def create_secret(self, secret: str) -> VonageApiSecret:
+        """Create an API secret for the account.
+
+        Args:
+            secret (VonageSecret): The secret to create. Must satisfy the following
+                conditions:
+                - 8-25 characters long
+                - At least one uppercase letter
+                - At least one lowercase letter
+                - At least one digit
+
+        Returns:
+            VonageApiSecret: The created VonageApiSecret object.
         """
-        pass
+        if not self._is_valid_secret(secret):
+            raise InvalidSecretError(
+                'Secret must be 8-25 characters long and contain at least one uppercase '
+                'letter, one lowercase letter, and one digit.'
+            )
+
+        response = self._http_client.post(
+            self._http_client.api_host,
+            f'/accounts/{self._http_client.auth.api_key}/secrets',
+            params={'secret': secret},
+            auth_type=self._auth_type,
+        )
+        return VonageApiSecret(**response)
+
+    @validate_call
+    def get_secret(self, secret_id: str) -> VonageApiSecret:
+        """Get a specific secret associated with the account.
+
+        Args:
+            secret_id (str): The ID of the secret to retrieve.
+
+        Returns:
+            VonageApiSecret: The VonageApiSecret object.
+        """
+        response = self._http_client.get(
+            self._http_client.api_host,
+            f'/accounts/{self._http_client.auth.api_key}/secrets/{secret_id}',
+            auth_type=self._auth_type,
+        )
+        return VonageApiSecret(**response)
+
+    @validate_call
+    def revoke_secret(self, secret_id: str) -> None:
+        """Revoke a specific secret associated with the account.
+
+        Args:
+            secret_id (str): The ID of the secret to revoke.
+        """
+        self._http_client.delete(
+            self._http_client.api_host,
+            f'/accounts/{self._http_client.auth.api_key}/secrets/{secret_id}',
+            auth_type=self._auth_type,
+        )
+
+    def _is_valid_secret(self, secret: str) -> bool:
+        if len(secret) < 8 or len(secret) > 25:
+            return False
+        if not re.search(r'[a-z]', secret):
+            return False
+        if not re.search(r'[A-Z]', secret):
+            return False
+        if not re.search(r'\d', secret):
+            return False
+        return True

account/src/vonage_account/errors.py

@@ -1,5 +1,5 @@
 from vonage_utils.errors import VonageError
 
 
-class AccountError(VonageError):
-    """Indicates an error with the Account package."""
+class InvalidSecretError(VonageError):
+    """Indicates that the secret provided was invalid."""

account/src/vonage_account/requests.py

@@ -3,6 +3,11 @@
 from pydantic import BaseModel, Field
 
 
+class Balance(BaseModel):
+    value: float
+    auto_reload: Optional[bool] = Field(None, validation_alias='autoReload')
+
+
 class TopUpResponse(BaseModel):
     error_code: Optional[str] = Field(None, validation_alias='error-code')
     error_code_label: Optional[str] = Field(None, validation_alias='error-code-label')
@@ -20,3 +25,8 @@ class SettingsResponse(BaseModel):
     max_calls_per_second: Optional[int] = Field(
         None, validation_alias='max-calls-per-second'
     )
+
+
+class VonageApiSecret(BaseModel):
+    id: str
+    created_at: str

account/src/vonage_account/responses.py

@@ -0,0 +1,6 @@
+{
+    "type": "https://developer.nexmo.com/api-errors/account/secret-management#add-excess-secret",
+    "title": "Secret Addition Forbidden",
+    "detail": "Account reached maximum number [2] of allowed secrets",
+    "instance": "48898273-7ae1-4ce4-8125-a71058ca6069"
+}

account/tests/data/create_secret_error_max_number.json

@@ -0,0 +1,20 @@
+{
+    "_links": {
+        "self": {
+            "href": "/accounts/test_api_key/secrets"
+        }
+    },
+    "_embedded": {
+        "secrets": [
+            {
+                "_links": {
+                    "self": {
+                        "href": "/accounts/test_api_key/secrets/1b1b1b1b-1b1b-1b-1b1b-1b1b1b1b1b1b"
+                    }
+                },
+                "id": "1b1b1b1b-1b1b-1b-1b1b-1b1b1b1b1b1b",
+                "created_at": "2022-03-28T14:16:56Z"
+            }
+        ]
+    }
+}

account/tests/data/list_secrets.json

@@ -0,0 +1,6 @@
+{
+    "type": "https://developer.nexmo.com/api-errors/account/secret-management#delete-last-secret",
+    "title": "Secret Deletion Forbidden",
+    "detail": "Can not delete the last secret. The account must always have at least 1 secret active at any time",
+    "instance": "a845d164-5623-4cc1-b7c6-0f95b94c6e53"
+}