Add the simple editor email endpoints to the SDK

VERSION

@@ -1 +1 @@
-0.1.3
+0.3.0

mailerlite/__init__.py

@@ -3,12 +3,28 @@
 from __future__ import absolute_import
 
 from mailerlite.api_client import ApiClient
+from mailerlite.exceptions import (  # noqa: F401
+    ApiError,
+    EmptyIdError,
+    InvalidIdError,
+)
+from mailerlite.response import ApiResponse  # noqa: F401
 from mailerlite.sdk.automations import Automations
 from mailerlite.sdk.batch import Batches
+from mailerlite.sdk.brand_styles import BrandStyles
 
 # import all api files into api package
 from mailerlite.sdk.campaigns import Campaigns
+from mailerlite.sdk.emails import (  # noqa: F401
+    EDITOR_SIMPLE,
+    VERSION_CONFLICT,
+    BlockPosition,
+    BlockType,
+    BrandMode,
+    Emails,
+)
 from mailerlite.sdk.fields import Fields
+from mailerlite.sdk.files import FileSort, Files, FileType  # noqa: F401
 from mailerlite.sdk.forms import Forms
 from mailerlite.sdk.groups import Groups
 from mailerlite.sdk.segments import Segments
@@ -29,6 +45,9 @@ def __init__(self, config={}):
         self.fields = Fields(self.api_client)
         self.forms = Forms(self.api_client)
         self.campaigns = Campaigns(self.api_client)
+        self.emails = Emails(self.api_client)
+        self.brand_styles = BrandStyles(self.api_client)
+        self.files = Files(self.api_client)
         self.timezones = Timezones(self.api_client)
         self.webhooks = Webhooks(self.api_client)
         self.automations = Automations(self.api_client)

mailerlite/api_client.py

@@ -6,17 +6,20 @@
 from functools import partialmethod
 from typing import Optional, Tuple
 
+from mailerlite.exceptions import ApiError
+
 
 class HttpMethods(object):
     """Allowed Http methods"""
 
     GET: str = "get"
     POST: str = "post"
     PUT: str = "put"
+    PATCH: str = "patch"
     DELETE: str = "delete"
 
     # Allowed methods
-    ALLOWED: Tuple[str, ...] = (GET, POST, PUT, DELETE)
+    ALLOWED: Tuple[str, ...] = (GET, POST, PUT, PATCH, DELETE)
 
     @classmethod
     def _is_method(cls, method: str, target: str) -> bool:
@@ -26,6 +29,7 @@ def _is_method(cls, method: str, target: str) -> bool:
     is_get: partialmethod = partialmethod(_is_method, target=GET)
     is_post: partialmethod = partialmethod(_is_method, target=POST)
     is_put: partialmethod = partialmethod(_is_method, target=PUT)
+    is_patch: partialmethod = partialmethod(_is_method, target=PATCH)
     is_delete: partialmethod = partialmethod(_is_method, target=DELETE)
 
 
@@ -73,24 +77,32 @@ def request(
         path: str,
         query_params: Optional[dict] = None,
         body: Optional[dict] = None,
+        headers: Optional[dict] = None,
     ) -> requests.models.Response:
-        """Requests Wrapper"""
+        """Requests Wrapper
+
+        `headers` are added to the default headers for this request only.
+        """
 
         method = method.lower()
         if method not in HttpMethods.ALLOWED:
-            raise ValueError("http method must be `POST`, `GET`, `PUT` or `DELETE`.")
+            raise ValueError(
+                "http method must be `POST`, `GET`, `PUT`, `PATCH` or `DELETE`."
+            )
 
         kwargs = {
             "method": method,
             "url": urljoin(self.HOST, path),
             "params": query_params,
-            "headers": self.headers,
+            "headers": {**self.headers, **(headers or {})},
             "timeout": self.timeout,
         }
         if HttpMethods.is_get(method):
             kwargs.update(allow_redirects=True)
-        if HttpMethods.is_post(method) or HttpMethods.is_put(method):
+        # Without a body, send no body and not the JSON `null`
+        if not HttpMethods.is_get(method) and body is not None:
             kwargs.update(data=json.dumps(body))
         response = requests.request(**kwargs)
-        response.raise_for_status()
+        if 400 <= response.status_code < 600:
+            raise ApiError(response)
         return response

mailerlite/exceptions.py

@@ -0,0 +1,53 @@
+from __future__ import absolute_import
+
+import requests
+
+
+class ApiError(requests.HTTPError):
+    """
+    The API returned a 4xx or 5xx status code
+
+    It is a `requests.HTTPError`, so `e.response` gives the full response.
+    The fields are `None` when the response body does not have them.
+    """
+
+    def __init__(self, response):
+        self.status_code = response.status_code
+
+        body = _json_or_none(response)
+        if not isinstance(body, dict):
+            body = {}
+
+        self.message = body.get("message")
+        self.code = body.get("code")
+        self.etag = body.get("etag")
+        self.errors = body.get("errors")
+
+        kind = "Client Error" if response.status_code < 500 else "Server Error"
+        text = (
+            f"{response.status_code} {kind}: {response.reason} for url: {response.url}"
+        )
+        if self.message:
+            detail = f"{self.code}: {self.message}" if self.code else self.message
+            text = f"{text} ({detail})"
+
+        super().__init__(text, response=response)
+
+    def __reduce__(self):
+        # pickle calls cls(*self.args) by default, but __init__ needs the response
+        return self.__class__, (self.response,)
+
+
+def _json_or_none(response):
+    try:
+        return response.json()
+    except ValueError:
+        return None
+
+
+class EmptyIdError(ValueError):
+    """An ID for the URL path is empty. The SDK sends no request."""
+
+
+class InvalidIdError(ValueError):
+    """An ID for the URL path does not contain only digits. The SDK sends no request."""

mailerlite/response.py

@@ -0,0 +1,48 @@
+from __future__ import absolute_import
+
+import copy
+
+
+class ApiResponse(dict):
+    """
+    The decoded JSON body of a response
+
+    It is a dict, so you use it like the dicts that the other methods return.
+    It also has the status code and the headers of the response.
+    A response without a body, for example `204`, is an empty dict.
+    """
+
+    def __init__(self, response):
+        super().__init__(_json_object(response))
+        self.status_code = response.status_code
+        self.headers = response.headers
+
+    def copy(self):
+        """A shallow copy that keeps the status code and the headers"""
+
+        return copy.copy(self)
+
+    @property
+    def is_idempotent_replay(self):
+        """
+        True if the API returned the stored response of an earlier request
+        with the same idempotency key
+        """
+
+        # A proxy can change the case of the value
+        value = self.headers.get("Idempotent-Replayed", "")
+        return value.strip().lower() == "true"
+
+
+def _json_object(response):
+    if not response.content:
+        return {}
+
+    body = response.json()
+    if not isinstance(body, dict):
+        raise TypeError(
+            f"The API returned a JSON {type(body).__name__}, not a JSON object, "
+            f"with status {response.status_code} for url: {response.url}"
+        )
+
+    return body

mailerlite/sdk/__init__.py

@@ -1,8 +1,11 @@
 from __future__ import absolute_import
 
 # import all api files into api package
+from mailerlite.sdk.brand_styles import BrandStyles
 from mailerlite.sdk.campaigns import Campaigns
+from mailerlite.sdk.emails import Emails
 from mailerlite.sdk.fields import Fields
+from mailerlite.sdk.files import Files
 from mailerlite.sdk.forms import Forms
 from mailerlite.sdk.groups import Groups
 from mailerlite.sdk.segments import Segments

mailerlite/sdk/_params.py

@@ -0,0 +1,52 @@
+from __future__ import absolute_import
+
+import re
+
+from mailerlite.exceptions import EmptyIdError, InvalidIdError
+
+_ID_PATTERN = re.compile(r"[0-9]+")
+
+
+def path_id(value, name):
+    if value is None or value == "":
+        raise EmptyIdError(f"`{name}` must not be empty.")
+
+    if isinstance(value, bool) or not isinstance(value, (str, int)):
+        raise TypeError(
+            f"`{name}` type is not valid. Expected `str` or `int`, got {type(value)}."
+        )
+
+    value = str(value)
+    # fullmatch, because `$` also matches before a final new line,
+    # and str.isdigit() also accepts digits that are not ASCII.
+    if not _ID_PATTERN.fullmatch(value):
+        raise InvalidIdError(f"`{name}` must contain only digits, got {value!r}.")
+
+    return value
+
+
+def require_dict(value, name):
+    if not isinstance(value, dict):
+        raise TypeError(
+            f"`{name}` type is not valid. Expected `dict`, got {type(value)}."
+        )
+
+
+def without_none(params):
+    return {key: value for key, value in params.items() if value is not None}
+
+
+def filter_params(filter):
+    if filter is None:
+        return {}
+
+    require_dict(filter, "filter")
+
+    return {f"filter[{key}]": value for key, value in without_none(filter).items()}
+
+
+def idempotency_headers(key):
+    if key is None:
+        return None
+
+    return {"Idempotency-Key": key}

mailerlite/sdk/brand_styles.py

@@ -0,0 +1,26 @@
+from __future__ import absolute_import
+
+from mailerlite.response import ApiResponse
+
+
+class BrandStyles(object):
+    # Brand styles base API uri
+    base_api_url = "api/brand-styles"
+
+    def __init__(self, api_client):
+        self.api_client = api_client
+
+    def get(self):
+        """
+        Get the brand styles
+
+        Returns the palettes of the account: `brand` (the brand styles of the
+        account, or `None` if it has none), `default` and the `presets`.
+        Match a palette on its `identifier`, not on its `name`.
+
+        :raises: :class: `ApiError` : API request failed
+        :return: JSON object
+        :rtype: ApiResponse
+        """
+
+        return ApiResponse(self.api_client.request("GET", self.base_api_url))

mailerlite/sdk/campaigns.py

@@ -13,6 +13,12 @@ def create(self, campaign):
         Create a campaign
         Ref: https://developers.mailerlite.com/docs/campaigns.html#create-a-campaign
 
+        To build the emails with the simple editor, set `editor` to `EDITOR_SIMPLE`
+        in each email, and do not send `content`. Then edit the emails with
+        `client.emails`. `template_id` is optional: a shared template of the
+        simple editor to start from. It needs `editor`. All emails of the campaign
+        must have the same `editor` and `template_id`.
+
         :param campaign: dict A dict that contains all campaign related arguments
         :return: JSON array
         :rtype: dict
@@ -27,6 +33,8 @@ def update(self, campaign_id, campaign):
         Provides ability to update single campaign.
         Ref: https://developers.mailerlite.com/docs/campaigns.html#update-campaign
 
+        Only `create()` accepts `editor` and `template_id` in the emails.
+
         :param campaign_id: int Id of the campaign
         :param campaign: dict A dict that contains all campaign related arguments
         :return: JSON array