Fix issue #42: Add GeneralApi, related models, examples, tests.

Ihor-Bilous · web-flow · commit d50e2d46df64 · 2025-10-06T13:41:49.000+03:00
diff --git a/examples/general/__init__.py b/examples/general/__init__.py
diff --git a/examples/general/account_accesses.py b/examples/general/account_accesses.py
@@ -0,0 +1,23 @@
+import mailtrap as mt
+from mailtrap.models.accounts import AccountAccess
+from mailtrap.models.common import DeletedObject
+
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+
+client = mt.MailtrapClient(token=API_TOKEN)
+account_accesses_api = client.general_api.account_accesses
+
+
+def get_account_accesses(account_id: int) -> list[AccountAccess]:
+    return account_accesses_api.get_list(account_id=account_id)
+
+
+def delete_account_access(account_id: int, account_access_id: int) -> DeletedObject:
+    return account_accesses_api.delete(
+        account_id=account_id, account_access_id=account_access_id
+    )
+
+
+if __name__ == "__main__":
+    print(get_account_accesses(ACCOUNT_ID))
diff --git a/examples/general/accounts.py b/examples/general/accounts.py
@@ -0,0 +1,15 @@
+import mailtrap as mt
+from mailtrap.models.accounts import Account
+
+API_TOKEN = "YOUR_API_TOKEN"
+
+client = mt.MailtrapClient(token=API_TOKEN)
+accounts_api = client.general_api.accounts
+
+
+def get_accounts() -> list[Account]:
+    return accounts_api.get_list()
+
+
+if __name__ == "__main__":
+    print(get_accounts())
diff --git a/examples/general/billing.py b/examples/general/billing.py
@@ -0,0 +1,16 @@
+import mailtrap as mt
+from mailtrap.models.billing import BillingCycleUsage
+
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+
+client = mt.MailtrapClient(token=API_TOKEN)
+billing_api = client.general_api.billing
+
+
+def get_current_billing_usage(account_id: int) -> BillingCycleUsage:
+    return billing_api.get_current_billing_usage(account_id=account_id)
+
+
+if __name__ == "__main__":
+    print(get_current_billing_usage(ACCOUNT_ID))
diff --git a/examples/general/permissions.py b/examples/general/permissions.py
@@ -0,0 +1,29 @@
+import mailtrap as mt
+from mailtrap.models.permissions import PermissionResource
+from mailtrap.models.permissions import UpdatePermissionsResponse
+
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+
+client = mt.MailtrapClient(token=API_TOKEN)
+permissions_api = client.general_api.permissions
+
+
+def get_permission_resources(account_id: int) -> list[PermissionResource]:
+    return permissions_api.get_resources(account_id=account_id)
+
+
+def bulk_permissions_update(
+    account_id: int,
+    account_access_id: int,
+    permissions: list[mt.PermissionResourceParams],
+) -> UpdatePermissionsResponse:
+    return permissions_api.bulk_permissions_update(
+        account_id=account_id,
+        account_access_id=account_access_id,
+        permissions=permissions,
+    )
+
+
+if __name__ == "__main__":
+    print(get_permission_resources(ACCOUNT_ID))
diff --git a/mailtrap/__init__.py b/mailtrap/__init__.py
@@ -5,6 +5,7 @@
 from .exceptions import AuthorizationError
 from .exceptions import ClientConfigurationError
 from .exceptions import MailtrapError
+from .models.accounts import AccountAccessFilterParams
 from .models.contacts import ContactListParams
 from .models.contacts import CreateContactFieldParams
 from .models.contacts import CreateContactParams
@@ -24,6 +25,7 @@
 from .models.mail import Mail
 from .models.mail import MailFromTemplate
 from .models.messages import UpdateEmailMessageParams
+from .models.permissions import PermissionResourceParams
 from .models.projects import ProjectParams
 from .models.templates import CreateEmailTemplateParams
 from .models.templates import UpdateEmailTemplateParams
diff --git a/mailtrap/api/general.py b/mailtrap/api/general.py
@@ -0,0 +1,26 @@
+from mailtrap.api.resources.account_accesses import AccountAccessesApi
+from mailtrap.api.resources.accounts import AccountsApi
+from mailtrap.api.resources.billing import BillingApi
+from mailtrap.api.resources.permissions import PermissionsApi
+from mailtrap.http import HttpClient
+
+
+class GeneralApi:
+    def __init__(self, client: HttpClient) -> None:
+        self._client = client
+
+    @property
+    def accounts(self) -> AccountsApi:
+        return AccountsApi(client=self._client)
+
+    @property
+    def account_accesses(self) -> AccountAccessesApi:
+        return AccountAccessesApi(client=self._client)
+
+    @property
+    def billing(self) -> BillingApi:
+        return BillingApi(client=self._client)
+
+    @property
+    def permissions(self) -> PermissionsApi:
+        return PermissionsApi(client=self._client)
diff --git a/mailtrap/api/resources/account_accesses.py b/mailtrap/api/resources/account_accesses.py
@@ -0,0 +1,43 @@
+from typing import Optional
+from urllib.parse import quote
+
+from mailtrap.http import HttpClient
+from mailtrap.models.accounts import AccountAccess
+from mailtrap.models.accounts import AccountAccessFilterParams
+from mailtrap.models.common import DeletedObject
+
+
+class AccountAccessesApi:
+    def __init__(self, client: HttpClient) -> None:
+        self._client = client
+
+    def get_list(
+        self, account_id: int, filter_params: Optional[AccountAccessFilterParams] = None
+    ) -> list[AccountAccess]:
+        """
+        Get list of account accesses for which specifier_type is User or Invite.
+        You have to have account admin/owner permissions for this endpoint to work.
+        If you specify project_ids, inbox_ids or domain_ids, the endpoint will return
+        account accesses for these resources.
+        """
+        response = self._client.get(
+            self._api_path(account_id),
+            params=filter_params.api_data if filter_params else None,
+        )
+        return [AccountAccess(**account_access) for account_access in response]
+
+    def delete(self, account_id: int, account_access_id: int) -> DeletedObject:
+        """
+        If specifier type is User, it removes user permissions.
+        If specifier type is Invite or ApiToken, it removes specifier
+        along with permissions. You have to be an account admin/owner
+        for this method to work.
+        """
+        self._client.delete(self._api_path(account_id, account_access_id))
+        return DeletedObject(account_access_id)
+
+    def _api_path(self, account_id: int, account_access_id: Optional[int] = None) -> str:
+        path = f"/api/accounts/{account_id}/account_accesses"
+        if account_access_id is not None:
+            return f"{path}/{quote(str(account_access_id), safe='')}"
+        return path
diff --git a/mailtrap/api/resources/accounts.py b/mailtrap/api/resources/accounts.py
@@ -0,0 +1,12 @@
+from mailtrap.http import HttpClient
+from mailtrap.models.accounts import Account
+
+
+class AccountsApi:
+    def __init__(self, client: HttpClient) -> None:
+        self._client = client
+
+    def get_list(self) -> list[Account]:
+        """Get a list of your Mailtrap accounts."""
+        response = self._client.get("/api/accounts")
+        return [Account(**account) for account in response]
diff --git a/mailtrap/api/resources/billing.py b/mailtrap/api/resources/billing.py
@@ -0,0 +1,12 @@
+from mailtrap.http import HttpClient
+from mailtrap.models.billing import BillingCycleUsage
+
+
+class BillingApi:
+    def __init__(self, client: HttpClient) -> None:
+        self._client = client
+
+    def get_current_billing_usage(self, account_id: int) -> BillingCycleUsage:
+        """Get current billing cycle usage for Email Testing and Email Sending."""
+        response = self._client.get(f"/api/accounts/{account_id}/billing/usage")
+        return BillingCycleUsage(**response)
diff --git a/mailtrap/api/resources/permissions.py b/mailtrap/api/resources/permissions.py
@@ -0,0 +1,39 @@
+from mailtrap.http import HttpClient
+from mailtrap.models.permissions import PermissionResource
+from mailtrap.models.permissions import PermissionResourceParams
+from mailtrap.models.permissions import UpdatePermissionsResponse
+
+
+class PermissionsApi:
+    def __init__(self, client: HttpClient) -> None:
+        self._client = client
+
+    def get_resources(self, account_id: int) -> list[PermissionResource]:
+        """
+        Get all resources in your account (Inboxes, Projects, Domains,
+        Email Campaigns, Billing and Account itself) to which the token
+        has admin access.
+        """
+        response = self._client.get(f"/api/accounts/{account_id}/permissions/resources")
+        return [PermissionResource(**resource) for resource in response]
+
+    def bulk_permissions_update(
+        self,
+        account_id: int,
+        account_access_id: int,
+        permissions: list[PermissionResourceParams],
+    ) -> UpdatePermissionsResponse:
+        """
+        Manage user or token permissions. For this endpoint, you should send
+        an array of objects (in JSON format) as the body of the request.
+        If you send a combination of resource_type and resource_id that already exists,
+        the permission is updated. If the combination doesn't exist,
+        the permission is created.
+        """
+        response = self._client.put(
+            f"/api/accounts/{account_id}"
+            f"/account_accesses/{account_access_id}"
+            "/permissions/bulk",
+            json={"permissions": [resource.api_data for resource in permissions]},
+        )
+        return UpdatePermissionsResponse(**response)
diff --git a/mailtrap/client.py b/mailtrap/client.py
@@ -6,6 +6,7 @@
 from pydantic import TypeAdapter
 
 from mailtrap.api.contacts import ContactsBaseApi
+from mailtrap.api.general import GeneralApi
 from mailtrap.api.sending import SendingApi
 from mailtrap.api.suppressions import SuppressionsBaseApi
 from mailtrap.api.templates import EmailTemplatesApi
@@ -53,6 +54,12 @@ def __init__(
 
         self._validate_itself()
 
+    @property
+    def general_api(self) -> GeneralApi:
+        return GeneralApi(
+            client=HttpClient(host=GENERAL_HOST, headers=self.headers),
+        )
+
     @property
     def testing_api(self) -> TestingApi:
         self._validate_account_id()
diff --git a/mailtrap/models/accounts.py b/mailtrap/models/accounts.py
@@ -0,0 +1,44 @@
+from typing import Optional
+
+from pydantic.dataclasses import dataclass
+
+from mailtrap.models.common import RequestParams
+from mailtrap.models.permissions import Permissions
+
+
+@dataclass
+class AccountAccessFilterParams(RequestParams):
+    domain_ids: Optional[list[str]] = None
+    inbox_ids: Optional[list[str]] = None
+    project_ids: Optional[list[str]] = None
+
+
+@dataclass
+class Account:
+    id: int
+    name: str
+    access_levels: list[int]
+
+
+@dataclass
+class Specifier:
+    id: int
+    email: str
+    name: str
+    two_factor_authentication_enabled: bool
+
+
+@dataclass
+class AccountAccessResource:
+    resource_id: int
+    resource_type: str
+    access_level: int
+
+
+@dataclass
+class AccountAccess:
+    id: int
+    specifier_type: str
+    specifier: Specifier
+    resources: list[AccountAccessResource]
+    permissions: Permissions
diff --git a/mailtrap/models/billing.py b/mailtrap/models/billing.py
@@ -0,0 +1,50 @@
+from datetime import datetime
+
+from pydantic.dataclasses import dataclass
+
+
+@dataclass
+class MessagesCount:
+    current: int
+    limit: int
+
+
+@dataclass
+class UsageTesting:
+    sent_messages_count: MessagesCount
+    forwarded_messages_count: MessagesCount
+
+
+@dataclass
+class UsageSending:
+    sent_messages_count: MessagesCount
+
+
+@dataclass
+class Plan:
+    name: str
+
+
+@dataclass
+class Testing:
+    plan: Plan
+    usage: UsageTesting
+
+
+@dataclass
+class Sending:
+    plan: Plan
+    usage: UsageSending
+
+
+@dataclass
+class Billing:
+    cycle_start: datetime
+    cycle_end: datetime
+
+
+@dataclass
+class BillingCycleUsage:
+    billing: Billing
+    testing: Testing
+    sending: Sending
diff --git a/mailtrap/models/permissions.py b/mailtrap/models/permissions.py
@@ -1,9 +1,35 @@
+from typing import Optional
+
 from pydantic.dataclasses import dataclass
 
+from mailtrap.models.common import RequestParams
+
 
 @dataclass
 class Permissions:
     can_read: bool
     can_update: bool
     can_destroy: bool
     can_leave: bool
+
+
+@dataclass
+class PermissionResource:
+    id: int
+    name: str
+    type: str
+    access_level: int
+    resources: list["PermissionResource"]
+
+
+@dataclass
+class PermissionResourceParams(RequestParams):
+    resource_id: str
+    resource_type: str
+    access_level: Optional[str] = None
+    _destroy: Optional[bool] = None
+
+
+@dataclass
+class UpdatePermissionsResponse:
+    message: str
diff --git a/tests/unit/api/general/__init__.py b/tests/unit/api/general/__init__.py
diff --git a/tests/unit/api/general/test_account_accesses.py b/tests/unit/api/general/test_account_accesses.py
diff --git a/tests/unit/api/general/test_accounts.py b/tests/unit/api/general/test_accounts.py
diff --git a/tests/unit/api/general/test_billing.py b/tests/unit/api/general/test_billing.py
diff --git a/tests/unit/api/general/test_permissions.py b/tests/unit/api/general/test_permissions.py
diff --git a/tests/unit/models/test_permissions.py b/tests/unit/models/test_permissions.py
