Minor/v0.4.0 more entities (#19)

* refactor: implement Synchronizable mixin and restructure model hierarchy to improve extensibility and API coverage

* refactor: implement idempotent-aware retries, add raw download support, and improve model update and synchronization logic

Author: TimEvci

moneysnake/__init__.py

@@ -3,6 +3,7 @@
 from .client import make_request as make_request
 from .client import paginate as paginate
 from .client import set_admin_id as set_admin_id
+from .client import set_max_retries as set_max_retries
 from .client import set_timeout as set_timeout
 from .client import set_token as set_token
 from .contact import Contact as Contact
@@ -23,7 +24,12 @@
 from .model import Loadable as Loadable
 from .model import MoneybirdModel as MoneybirdModel
 from .model import Saveable as Saveable
+from .model import Synchronizable as Synchronizable
 from .payment import Payment as Payment
+from .sales_invoice import SalesInvoice as SalesInvoice
+from .sales_invoice import (
+    SalesInvoiceDetailsAttribute as SalesInvoiceDetailsAttribute,
+)
 from .tax_rate import TaxRate as TaxRate
 
 __all__ = [
@@ -32,6 +38,7 @@
     "make_request",
     "paginate",
     "set_admin_id",
+    "set_max_retries",
     "set_timeout",
     "set_token",
     "Contact",
@@ -50,6 +57,9 @@
     "MoneybirdRateLimitError",
     "MoneybirdValidationError",
     "Payment",
+    "SalesInvoice",
+    "SalesInvoiceDetailsAttribute",
     "Saveable",
+    "Synchronizable",
     "TaxRate",
 ]

moneysnake/client.py

@@ -1,7 +1,9 @@
 import logging
+import time
 from typing import Any
 
 import httpx
+from httpx import Response
 
 from .exceptions import (
     MoneybirdAPIError,
@@ -19,6 +21,7 @@
 admin_id_ = 0
 token_ = ""
 timeout_ = 20
+max_retries_ = 3
 
 
 def set_admin_id(admin_id: int) -> None:
@@ -36,6 +39,22 @@ def set_timeout(timeout: int) -> None:
     timeout_ = timeout
 
 
+def set_max_retries(max_retries: int) -> None:
+    global max_retries_
+    max_retries_ = max_retries
+
+
+_IDEMPOTENT_METHODS = frozenset({"get", "put", "delete", "head", "options"})
+
+
+def _is_retryable(status_code: int, method: str) -> bool:
+    if status_code == 429:
+        return True
+    if status_code >= 500 and method.lower() in _IDEMPOTENT_METHODS:
+        return True
+    return False
+
+
 def make_request(
     path: str,
     data: dict[str, Any] | None = None,
@@ -47,49 +66,101 @@ def make_request(
         "Content-Type": "application/json",
     }
     fullpath = f"{MB_URL}/{MB_VERSION_ID}/{admin_id_}/{path}"
-    logger.debug("%s %s", method.upper(), fullpath)
-    response = httpx.request(
-        method,
-        fullpath,
-        json=data,
-        headers=headers,
-        timeout=timeout_,
-        params=params,
-    )
-
-    try:
-        response.raise_for_status()
-    except httpx.HTTPStatusError as exc:
-        body = response.text
-        logger.warning(
-            "%s %s returned %d: %s",
-            method.upper(),
+
+    last_exc: httpx.HTTPStatusError | None = None
+    for attempt in range(max_retries_ + 1):
+        logger.debug("%s %s (attempt %d)", method.upper(), fullpath, attempt + 1)
+        response = httpx.request(
+            method,
             fullpath,
-            response.status_code,
-            body,
+            json=data,
+            headers=headers,
+            timeout=timeout_,
+            params=params,
         )
-        error_cls: type[MoneybirdAPIError] = {
-            404: MoneybirdNotFoundError,
-            422: MoneybirdValidationError,
-            429: MoneybirdRateLimitError,
-        }.get(response.status_code, MoneybirdAPIError)
-        raise error_cls(
-            status_code=response.status_code,
-            response_body=body,
-            method=method,
-            path=path,
-        ) from exc
 
-    logger.debug("%s %s returned %d", method.upper(), fullpath, response.status_code)
-
-    # return json if there is content
-    return response.json() if response.content else {}
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            last_exc = exc
+            if _is_retryable(response.status_code, method) and attempt < max_retries_:
+                retry_after = response.headers.get("Retry-After")
+                if retry_after:
+                    try:
+                        delay = int(retry_after)
+                    except ValueError:
+                        delay = 2 ** attempt
+                    delay = max(delay, 1)
+                else:
+                    delay = 2 ** attempt
+                logger.warning(
+                    "%s %s returned %d, retrying in %ds (attempt %d/%d)",
+                    method.upper(),
+                    fullpath,
+                    response.status_code,
+                    delay,
+                    attempt + 1,
+                    max_retries_ + 1,
+                )
+                time.sleep(delay)
+                continue
+
+            body = response.text
+            logger.warning(
+                "%s %s returned %d: %s",
+                method.upper(),
+                fullpath,
+                response.status_code,
+                body,
+            )
+            error_cls: type[MoneybirdAPIError] = {
+                404: MoneybirdNotFoundError,
+                422: MoneybirdValidationError,
+                429: MoneybirdRateLimitError,
+            }.get(response.status_code, MoneybirdAPIError)
+            raise error_cls(
+                status_code=response.status_code,
+                response_body=body,
+                method=method,
+                path=path,
+            ) from exc
+
+        logger.debug("%s %s returned %d", method.upper(), fullpath, response.status_code)
+        return response.json() if response.content else {}
+
+    # All retries exhausted — raise from last exception
+    assert last_exc is not None
+    body = last_exc.response.text
+    status_code = last_exc.response.status_code
+    error_cls = {
+        404: MoneybirdNotFoundError,
+        422: MoneybirdValidationError,
+        429: MoneybirdRateLimitError,
+    }.get(status_code, MoneybirdAPIError)
+    raise error_cls(
+        status_code=status_code,
+        response_body=body,
+        method=method,
+        path=path,
+    ) from last_exc
 
 
 def http_get(path: str, params: dict[str, Any] | None = None) -> Any:
     return make_request(path, method="get", params=params)
 
 
+def http_get_raw(path: str) -> Response:
+    """Perform a GET and return the raw httpx Response (for binary downloads)."""
+    headers = {
+        "Authorization": f"Bearer {token_}",
+    }
+    fullpath = f"{MB_URL}/{MB_VERSION_ID}/{admin_id_}/{path}"
+    logger.debug("GET %s (raw)", fullpath)
+    response = httpx.get(fullpath, headers=headers, timeout=timeout_)
+    response.raise_for_status()
+    return response
+
+
 def http_post(path: str, data: dict[str, Any] | None = None) -> Any:
     return make_request(path, method="post", data=data)
 

moneysnake/contact.py

@@ -4,15 +4,15 @@
 
 from .client import http_get
 from .custom_field_model import CustomFieldModel
-from .model import ensure_list_of
+from .model import Synchronizable, ensure_list_of
 
 
 class ContactPerson(BaseModel):
     firstname: str | None = None
     lastname: str | None = None
 
 
-class Contact(CustomFieldModel):
+class Contact(Synchronizable, CustomFieldModel):
     company_name: str | None = None
     address1: str | None = None
     address2: str | None = None

moneysnake/external_sales_invoice.py

@@ -1,9 +1,9 @@
-from typing import Any
+from typing import Any, Self
 
 from pydantic import BaseModel, Field, field_validator
 
 from .client import http_delete, http_patch, http_post, paginate
-from .model import CrudModel, ensure_list_of
+from .model import CrudModel, Synchronizable, ensure_list_of
 from .payment import Payment
 
 
@@ -22,13 +22,13 @@ class ExternalSalesInvoiceDetailsAttribute(BaseModel):
     project_id: str | None = None
 
     def update(self, data: dict[str, Any]) -> None:
-        for key, value in data.items():
-            if hasattr(self, key):
-                setattr(self, key, value)
+        validated = self.model_validate({**self.model_dump(), **data})
+        for key in self.__class__.model_fields:
+            object.__setattr__(self, key, getattr(validated, key))
 
 
 
-class ExternalSalesInvoice(CrudModel):
+class ExternalSalesInvoice(Synchronizable, CrudModel):
     """
     Represents an external sales invoice in Moneybird.
     """
@@ -115,20 +115,22 @@ def delete_detail(self, detail_id: int) -> None:
         if self.details:
             self.details = [detail for detail in self.details if detail.id != detail_id]
 
+    @classmethod
     def list_all_by_contact_id(
-        self,
+        cls,
         contact_id: int,
         state: str | None = "all",
         period: str | None = "this_year",
-    ) -> list["ExternalSalesInvoice"]:
+    ) -> list[Self]:
         """
         List all external sales invoices for a contact.
         """
+        endpoint = cls._sync_endpoint()
         data = paginate(
-            f"{self.endpoint}s",
+            f"{endpoint}s",
             params={"filter": f"contact_id:{contact_id},state:{state},period:{period}"},
         )
-        return [ExternalSalesInvoice(**item) for item in data]
+        return [cls(**item) for item in data]
 
     def create_payment(self, payment: Payment) -> None:
         """

moneysnake/financial_mutation.py

@@ -6,7 +6,7 @@
 from pydantic import Field
 
 from .client import http_delete, http_patch, paginate
-from .model import Loadable, MoneybirdModel
+from .model import Loadable, MoneybirdModel, Synchronizable
 
 
 class LinkBookingType(Enum):
@@ -37,7 +37,7 @@ class UnlinkBookingType(Enum):
     Payment = auto()
 
 
-class FinancialMutation(Loadable, MoneybirdModel):
+class FinancialMutation(Synchronizable, Loadable, MoneybirdModel):
     """
     Represents a financial mutation in Moneybird.
     """

moneysnake/model.py

@@ -2,7 +2,7 @@
 
 from pydantic import BaseModel, ConfigDict
 
-from .client import http_delete, http_get, http_patch, http_post
+from .client import http_delete, http_get, http_patch, http_post, paginate
 
 T = TypeVar("T", bound=BaseModel)
 
@@ -96,5 +96,47 @@ def delete_by_id(cls: type[Self], id: int) -> Self:
         return entity
 
 
+class Synchronizable(MoneybirdModel):
+    """Mixin that adds synchronization endpoints for efficient bulk data access."""
+
+    @classmethod
+    def sync_list(cls: type[Self], filter: str | None = None) -> list[dict[str, Any]]:
+        """Get all IDs and versions for this resource.
+
+        Returns a list of dicts with 'id' and 'version' keys, useful for
+        checking which records have changed since last sync.
+        """
+        params: dict[str, str] = {}
+        if filter:
+            params["filter"] = filter
+        return paginate(f"{cls._sync_endpoint()}s/synchronization", params=params or None)
+
+    @classmethod
+    def sync_fetch(cls: type[Self], ids: list[int]) -> list[Self]:
+        """Fetch full records by IDs (max 100 per request).
+
+        Use sync_list() first to get IDs, then fetch changed records in bulk.
+        """
+        if len(ids) > 100:
+            raise ValueError("sync_fetch supports a maximum of 100 IDs per request")
+        data = http_post(
+            f"{cls._sync_endpoint()}s/synchronization",
+            data={"ids": ids},
+        )
+        if not isinstance(data, list):
+            return []
+        return [cls(**item) for item in data]
+
+    @classmethod
+    def _sync_endpoint(cls) -> str:
+        """Derive the endpoint name for synchronization."""
+        pattr = cls.__private_attributes__.get("_endpoint")
+        if pattr is not None and pattr.default is not None:
+            return pattr.default
+        return "".join(
+            "_" + c.lower() if c.isupper() else c for c in cls.__name__
+        ).lstrip("_")
+
+
 class CrudModel(Loadable, Saveable, Deletable, MoneybirdModel):
     """Full CRUD model with load, save, and delete capabilities."""