Fix issue #19: Add ContactFieldsApi, related models, tests, examples

examples/contacts/contact_fields.py

@@ -0,0 +1,49 @@
+from typing import Optional
+
+import mailtrap as mt
+from mailtrap.models.common import DeletedObject
+from mailtrap.models.contacts import ContactField
+
+API_TOKEN = "YOU_API_TOKEN"
+ACCOUNT_ID = "YOU_ACCOUNT_ID"
+
+client = mt.MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
+contact_fields_api = client.contacts_api.contact_fields
+
+
+def create_contact_field(
+    name: str,
+    data_type: str,
+    merge_tag: str,
+) -> ContactField:
+    params = mt.CreateContactFieldParams(
+        name=name,
+        data_type=data_type,
+        merge_tag=merge_tag,
+    )
+    return contact_fields_api.create(params)
+
+
+def update_contact_field(
+    contact_field_id: int,
+    name: Optional[str] = None,
+    merge_tag: Optional[str] = None,
+) -> ContactField:
+    params = mt.UpdateContactFieldParams(name=name, merge_tag=merge_tag)
+    return contact_fields_api.update(contact_field_id, params)
+
+
+def list_contact_fields() -> list[ContactField]:
+    return contact_fields_api.get_list()
+
+
+def get_contact_field(contact_field_id: int) -> ContactField:
+    return contact_fields_api.get_by_id(contact_field_id)
+
+
+def delete_contact_field(contact_field_id: int) -> DeletedObject:
+    return contact_fields_api.delete(contact_field_id)
+
+
+if __name__ == "__main__":
+    print(list_contact_fields())

mailtrap/__init__.py

@@ -4,6 +4,9 @@
 from .exceptions import AuthorizationError
 from .exceptions import ClientConfigurationError
 from .exceptions import MailtrapError
+from .models.contacts import ContactField
+from .models.contacts import CreateContactFieldParams
+from .models.contacts import UpdateContactFieldParams
 from .models.mail import Address
 from .models.mail import Attachment
 from .models.mail import BaseMail

mailtrap/api/contacts.py

@@ -0,0 +1,12 @@
+from mailtrap.api.resources.contact_fields import ContactFieldsApi
+from mailtrap.http import HttpClient
+
+
+class ContactsBaseApi:
+    def __init__(self, client: HttpClient, account_id: str) -> None:
+        self._account_id = account_id
+        self._client = client
+
+    @property
+    def contact_fields(self) -> ContactFieldsApi:
+        return ContactFieldsApi(account_id=self._account_id, client=self._client)

mailtrap/api/resources/contact_fields.py

@@ -0,0 +1,49 @@
+from typing import Optional
+
+from mailtrap.http import HttpClient
+from mailtrap.models.common import DeletedObject
+from mailtrap.models.contacts import ContactField
+from mailtrap.models.contacts import CreateContactFieldParams
+from mailtrap.models.contacts import UpdateContactFieldParams
+
+
+class ContactFieldsApi:
+    def __init__(self, client: HttpClient, account_id: str) -> None:
+        self._account_id = account_id
+        self._client = client
+
+    def get_list(self) -> list[ContactField]:
+        response = self._client.get(self._api_path())
+        return [ContactField(**field) for field in response]
+
+    def get_by_id(self, field_id: int) -> ContactField:
+        response = self._client.get(
+            self._api_path(field_id),
+        )
+        return ContactField(**response)
+
+    def create(self, field_params: CreateContactFieldParams) -> ContactField:
+        response = self._client.post(
+            self._api_path(),
+            json=field_params.api_data,
+        )
+        return ContactField(**response)
+
+    def update(
+        self, field_id: int, field_params: UpdateContactFieldParams
+    ) -> ContactField:
+        response = self._client.patch(
+            self._api_path(field_id),
+            json=field_params.api_data,
+        )
+        return ContactField(**response)
+
+    def delete(self, field_id: int) -> DeletedObject:
+        self._client.delete(self._api_path(field_id))
+        return DeletedObject(field_id)
+
+    def _api_path(self, field_id: Optional[int] = None) -> str:
+        path = f"/api/accounts/{self._account_id}/contacts/fields"
+        if field_id:
+            return f"{path}/{field_id}"
+        return path

mailtrap/api/resources/projects.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from mailtrap.http import HttpClient
 from mailtrap.models.common import DeletedObject
 from mailtrap.models.projects import Project
@@ -9,31 +11,33 @@ def __init__(self, client: HttpClient, account_id: str) -> None:
         self._client = client
 
     def get_list(self) -> list[Project]:
-        response = self._client.get(f"/api/accounts/{self._account_id}/projects")
+        response = self._client.get(self._api_path())
         return [Project(**project) for project in response]
 
     def get_by_id(self, project_id: int) -> Project:
-        response = self._client.get(
-            f"/api/accounts/{self._account_id}/projects/{project_id}"
-        )
+        response = self._client.get(self._api_path(project_id))
         return Project(**response)
 
     def create(self, project_name: str) -> Project:
         response = self._client.post(
-            f"/api/accounts/{self._account_id}/projects",
+            self._api_path(),
             json={"project": {"name": project_name}},
         )
         return Project(**response)
 
     def update(self, project_id: int, project_name: str) -> Project:
         response = self._client.patch(
-            f"/api/accounts/{self._account_id}/projects/{project_id}",
+            self._api_path(project_id),
             json={"project": {"name": project_name}},
         )
         return Project(**response)
 
     def delete(self, project_id: int) -> DeletedObject:
-        response = self._client.delete(
-            f"/api/accounts/{self._account_id}/projects/{project_id}",
-        )
+        response = self._client.delete(self._api_path(project_id))
         return DeletedObject(**response)
+
+    def _api_path(self, project_id: Optional[int] = None) -> str:
+        path = f"/api/accounts/{self._account_id}/projects"
+        if project_id:
+            return f"{path}/{project_id}"
+        return path

mailtrap/api/resources/templates.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from mailtrap.http import HttpClient
 from mailtrap.models.common import DeletedObject
 from mailtrap.models.templates import CreateEmailTemplateParams
@@ -11,18 +13,16 @@ def __init__(self, client: HttpClient, account_id: str) -> None:
         self._client = client
 
     def get_list(self) -> list[EmailTemplate]:
-        response = self._client.get(f"/api/accounts/{self._account_id}/email_templates")
+        response = self._client.get(self._api_path())
         return [EmailTemplate(**template) for template in response]
 
     def get_by_id(self, template_id: int) -> EmailTemplate:
-        response = self._client.get(
-            f"/api/accounts/{self._account_id}/email_templates/{template_id}"
-        )
+        response = self._client.get(self._api_path(template_id))
         return EmailTemplate(**response)
 
     def create(self, template_params: CreateEmailTemplateParams) -> EmailTemplate:
         response = self._client.post(
-            f"/api/accounts/{self._account_id}/email_templates",
+            self._api_path(),
             json={"email_template": template_params.api_data},
         )
         return EmailTemplate(**response)
@@ -31,13 +31,17 @@ def update(
         self, template_id: int, template_params: UpdateEmailTemplateParams
     ) -> EmailTemplate:
         response = self._client.patch(
-            f"/api/accounts/{self._account_id}/email_templates/{template_id}",
+            self._api_path(template_id),
             json={"email_template": template_params.api_data},
         )
         return EmailTemplate(**response)
 
     def delete(self, template_id: int) -> DeletedObject:
-        self._client.delete(
-            f"/api/accounts/{self._account_id}/email_templates/{template_id}"
-        )
+        self._client.delete(self._api_path(template_id))
         return DeletedObject(template_id)
+
+    def _api_path(self, template_id: Optional[int] = None) -> str:
+        path = f"/api/accounts/{self._account_id}/email_templates"
+        if template_id:
+            return f"{path}/{template_id}"
+        return path

mailtrap/client.py

@@ -5,6 +5,7 @@
 
 from pydantic import TypeAdapter
 
+from mailtrap.api.contacts import ContactsBaseApi
 from mailtrap.api.sending import SendingApi
 from mailtrap.api.templates import EmailTemplatesApi
 from mailtrap.api.testing import TestingApi
@@ -63,6 +64,14 @@ def email_templates_api(self) -> EmailTemplatesApi:
             client=HttpClient(host=GENERAL_HOST, headers=self.headers),
         )
 
+    @property
+    def contacts_api(self) -> ContactsBaseApi:
+        self._validate_account_id()
+        return ContactsBaseApi(
+            account_id=cast(str, self.account_id),
+            client=HttpClient(host=GENERAL_HOST, headers=self.headers),
+        )
+
     @property
     def sending_api(self) -> SendingApi:
         http_client = HttpClient(host=self._sending_api_host, headers=self.headers)

mailtrap/models/contacts.py

@@ -0,0 +1,30 @@
+from typing import Optional
+
+from pydantic.dataclasses import dataclass
+
+from mailtrap.models.common import RequestParams
+
+
+@dataclass
+class CreateContactFieldParams(RequestParams):
+    name: str
+    data_type: str
+    merge_tag: str
+
+
+@dataclass
+class UpdateContactFieldParams(RequestParams):
+    name: Optional[str] = None
+    merge_tag: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if all(value is None for value in [self.name, self.merge_tag]):
+            raise ValueError("At least one field must be provided for update action")
+
+
+@dataclass
+class ContactField:
+    id: int
+    name: str
+    data_type: str
+    merge_tag: str