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

Author: Ihor Bilous

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: str,
+    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: str) -> ContactField:
+    return contact_fields_api.get_by_id(contact_field_id)
+
+
+def delete_contact_field(contact_field_id: str) -> 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,43 @@
+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(f"/api/accounts/{self._account_id}/contacts/fields")
+        return [ContactField(**field) for field in response]
+
+    def get_by_id(self, field_id: int) -> ContactField:
+        response = self._client.get(
+            f"/api/accounts/{self._account_id}/contacts/fields/{field_id}"
+        )
+        return ContactField(**response)
+
+    def create(self, field_params: CreateContactFieldParams) -> ContactField:
+        response = self._client.post(
+            f"/api/accounts/{self._account_id}/contacts/fields",
+            json=field_params.api_data,
+        )
+        return ContactField(**response)
+
+    def update(
+        self, field_id: int, field_params: UpdateContactFieldParams
+    ) -> ContactField:
+        response = self._client.patch(
+            f"/api/accounts/{self._account_id}/contacts/fields/{field_id}",
+            json=field_params.api_data,
+        )
+        return ContactField(**response)
+
+    def delete(self, field_id: int) -> DeletedObject:
+        self._client.delete(
+            f"/api/accounts/{self._account_id}/contacts/fields/{field_id}"
+        )
+        return DeletedObject(field_id)

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