Minor/v0.5.0 purchase invoices receipts (#20)

* feat: add Document base class for purchase invoices and receipts

* feat: add PurchaseInvoice model

* feat: add Receipt model

* feat: export Document, PurchaseInvoice, and Receipt

* test: add tests for PurchaseInvoice and Receipt

* chore: bump version to 0.5.0

* chore: bump project version to 0.5.0 in uv.lock

* refactor: remove section comments from document module and tests

* feat: track and submit destroyed document details via _destroy attribute during save

Author: TimEvci

moneysnake/__init__.py

@@ -25,7 +25,15 @@
 from .model import MoneybirdModel as MoneybirdModel
 from .model import Saveable as Saveable
 from .model import Synchronizable as Synchronizable
+from .document import Document as Document
+from .document import DocumentDetailsAttribute as DocumentDetailsAttribute
 from .payment import Payment as Payment
+from .purchase_invoice import PurchaseInvoice as PurchaseInvoice
+from .purchase_invoice import (
+    PurchaseInvoiceDetailsAttribute as PurchaseInvoiceDetailsAttribute,
+)
+from .receipt import Receipt as Receipt
+from .receipt import ReceiptDetailsAttribute as ReceiptDetailsAttribute
 from .sales_invoice import SalesInvoice as SalesInvoice
 from .sales_invoice import (
     SalesInvoiceDetailsAttribute as SalesInvoiceDetailsAttribute,
@@ -45,6 +53,8 @@
     "ContactPerson",
     "CrudModel",
     "Deletable",
+    "Document",
+    "DocumentDetailsAttribute",
     "ExternalSalesInvoice",
     "ExternalSalesInvoiceDetailsAttribute",
     "FinancialMutation",
@@ -57,6 +67,10 @@
     "MoneybirdRateLimitError",
     "MoneybirdValidationError",
     "Payment",
+    "PurchaseInvoice",
+    "PurchaseInvoiceDetailsAttribute",
+    "Receipt",
+    "ReceiptDetailsAttribute",
     "SalesInvoice",
     "SalesInvoiceDetailsAttribute",
     "Saveable",

moneysnake/document.py

@@ -0,0 +1,191 @@
+from typing import Any, ClassVar, Self
+
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, field_validator
+
+from .client import http_delete, http_get, http_patch, http_post, paginate
+from .model import Synchronizable, ensure_list_of
+from .payment import Payment
+
+
+class DocumentDetailsAttribute(BaseModel):
+    """Details attribute (line item) for a purchase invoice or receipt."""
+
+    id: int | None = None
+    description: str | None = None
+    period: str | None = None
+    price: int | str | None = None
+    amount: int | str | None = None
+    tax_rate_id: int | None = None
+    ledger_account_id: int | str | None = None
+    project_id: int | str | None = None
+    product_id: int | str | None = None
+    row_order: int | None = None
+    model_config = ConfigDict(extra="ignore")
+
+    def update(self, data: dict[str, Any]) -> None:
+        validated = self.model_validate({**self.model_dump(), **data})
+        for key in self.__class__.model_fields:
+            object.__setattr__(self, key, getattr(validated, key))
+
+
+class Document(Synchronizable):
+    """Base class for Moneybird document types (purchase invoices, receipts).
+
+    Subclasses must set ``_resource`` (e.g. ``"purchase_invoice"``). All requests
+    are routed under ``documents/{_resource}s``.
+    """
+
+    _resource: ClassVar[str]
+
+    contact_id: int | None = None
+    contact: dict[str, Any] | None = None
+    reference: str | None = None
+    date: str | None = None
+    due_date: str | None = None
+    entry_number: int | None = None
+    state: str | None = None
+    currency: str | None = None
+    exchange_rate: str | None = None
+    revenue_invoice: bool | None = None
+    prices_are_incl_tax: bool | None = None
+    origin: str | None = None
+    paid_at: str | None = None
+    tax_number: str | None = None
+    total_price_excl_tax: str | None = None
+    total_price_excl_tax_base: str | None = None
+    total_price_incl_tax: str | None = None
+    total_price_incl_tax_base: str | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+    version: int | None = None
+
+    details: list[DocumentDetailsAttribute] = Field(default_factory=list)
+    payments: list[Payment] = Field(default_factory=list)
+
+    _destroyed_detail_ids: list[int] = PrivateAttr(default_factory=list)
+
+    @field_validator("payments")
+    def ensure_payments(
+        cls, value: list[dict[str, Any]] | list[Payment] | None
+    ) -> list[Payment]:
+        if value is None:
+            return []
+        return ensure_list_of(Payment, value)
+
+    @field_validator("details")
+    def ensure_details(
+        cls,
+        value: list[dict[str, Any]] | list[DocumentDetailsAttribute] | None,
+    ) -> list[DocumentDetailsAttribute]:
+        if value is None:
+            return []
+        return ensure_list_of(DocumentDetailsAttribute, value)
+
+    @classmethod
+    def _base_path(cls) -> str:
+        return f"documents/{cls._resource}s"
+
+    @classmethod
+    def _sync_endpoint(cls) -> str:
+        return f"documents/{cls._resource}"
+
+    def load(self, id: int) -> None:
+        data = http_get(f"{self._base_path()}/{id}")
+        self.update(data)
+
+    @classmethod
+    def find_by_id(cls: type[Self], id: int) -> Self:
+        entity = cls(id=id)
+        entity.load(id)
+        return entity
+
+    def save(self) -> None:
+        body = self.to_dict()
+        details = body.pop("details", [])
+        for detail_id in self._destroyed_detail_ids:
+            details.append({"id": detail_id, "_destroy": True})
+        body["details_attributes"] = details
+
+        if self.id is None:
+            data = http_post(self._base_path(), data={self._resource: body})
+        else:
+            data = http_patch(
+                f"{self._base_path()}/{self.id}", data={self._resource: body}
+            )
+        self._destroyed_detail_ids.clear()
+        self.update(data)
+
+    def delete(self) -> None:
+        if not self.id:
+            raise ValueError(f"Cannot delete {self.__class__.__name__} without an id")
+        http_delete(f"{self._base_path()}/{self.id}")
+        self.id = None
+
+    def add_detail(self, detail: DocumentDetailsAttribute) -> None:
+        self.details.append(detail)
+
+    def get_detail(self, detail_id: int) -> DocumentDetailsAttribute:
+        for detail in self.details:
+            if detail.id == detail_id:
+                return detail
+        raise ValueError(f"Detail with id {detail_id} not found.")
+
+    def update_detail(
+        self, detail_id: int, data: dict[str, Any]
+    ) -> DocumentDetailsAttribute:
+        detail = self.get_detail(detail_id)
+        detail.update(data)
+        return detail
+
+    def delete_detail(self, detail_id: int) -> None:
+        detail = self.get_detail(detail_id)
+        if detail.id is not None:
+            self._destroyed_detail_ids.append(detail.id)
+        self.details = [d for d in self.details if d.id != detail_id]
+
+    def create_payment(self, payment: Payment) -> None:
+        data = http_post(
+            path=f"{self._base_path()}/{self.id}/payments",
+            data={"payment": payment.to_dict()},
+        )
+        payment_data = data.get("payment")
+        if payment_data:
+            self.payments.append(Payment(**payment_data))
+
+    def delete_payment(self, payment_id: int) -> None:
+        http_delete(path=f"{self._base_path()}/{self.id}/payments/{payment_id}")
+        self.payments = [p for p in self.payments if p.id != payment_id]
+
+    def register_payment(self, payment: Payment) -> None:
+        """Register a payment via the register_payment endpoint."""
+        data = http_post(
+            f"{self._base_path()}/{self.id}/register_payment",
+            data={"payment": payment.to_dict()},
+        )
+        self.update(data)
+
+    @classmethod
+    def list_all(
+        cls,
+        state: str | None = None,
+        period: str | None = None,
+        contact_id: int | None = None,
+        reference: str | None = None,
+    ) -> list[Self]:
+        """List documents with optional filters."""
+        filter_parts: list[str] = []
+        if state:
+            filter_parts.append(f"state:{state}")
+        if period:
+            filter_parts.append(f"period:{period}")
+        if contact_id:
+            filter_parts.append(f"contact_id:{contact_id}")
+        if reference:
+            filter_parts.append(f"reference:{reference}")
+
+        params: dict[str, str] = {}
+        if filter_parts:
+            params["filter"] = ",".join(filter_parts)
+
+        data = paginate(cls._base_path(), params=params or None)
+        return [cls(**item) for item in data]

moneysnake/purchase_invoice.py

@@ -0,0 +1,11 @@
+from .document import Document, DocumentDetailsAttribute
+
+
+class PurchaseInvoiceDetailsAttribute(DocumentDetailsAttribute):
+    """Details attribute (line item) for a purchase invoice."""
+
+
+class PurchaseInvoice(Document):
+    """Represents a purchase invoice in Moneybird."""
+
+    _resource = "purchase_invoice"

moneysnake/receipt.py

@@ -0,0 +1,11 @@
+from .document import Document, DocumentDetailsAttribute
+
+
+class ReceiptDetailsAttribute(DocumentDetailsAttribute):
+    """Details attribute (line item) for a receipt."""
+
+
+class Receipt(Document):
+    """Represents a receipt in Moneybird."""
+
+    _resource = "receipt"

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "moneysnake"
-version = "0.4.0"
+version = "0.5.0"
 description = "Moneybird SDK for Python"
 authors = [{ name = "ArjanCodes" }]
 license = { text = "MIT" }

tests/conftest.py

@@ -89,6 +89,58 @@ def fixture_contact_data() -> dict[str, Any]:
     }
 
 
+@pytest.fixture(name="document_data")
+def fixture_document_data() -> dict[str, Any]:
+    """Full purchase invoice / receipt response matching Moneybird OpenAPI document schema."""
+    return {
+        "id": "480487019028416410",
+        "administration_id": 123,
+        "contact_id": "480487019000104856",
+        "contact": {
+            "id": "480487019000104856",
+            "company_name": "Foobar Holding B.V.",
+        },
+        "reference": "2026-01234",
+        "date": "2026-04-27",
+        "due_date": "2026-05-11",
+        "entry_number": 1,
+        "state": "open",
+        "currency": "EUR",
+        "exchange_rate": "1.0",
+        "revenue_invoice": False,
+        "prices_are_incl_tax": False,
+        "origin": None,
+        "paid_at": None,
+        "tax_number": None,
+        "total_price_excl_tax": "99.0",
+        "total_price_excl_tax_base": "99.0",
+        "total_price_incl_tax": "119.79",
+        "total_price_incl_tax_base": "119.79",
+        "created_at": "2026-04-27T10:00:00.000Z",
+        "updated_at": "2026-04-27T10:00:00.000Z",
+        "version": 1772448151,
+        "details": [
+            {
+                "id": "480487019122788274",
+                "administration_id": 123,
+                "tax_rate_id": "480486875411252364",
+                "ledger_account_id": "480486875195245688",
+                "project_id": None,
+                "product_id": None,
+                "amount": "1",
+                "amount_decimal": "1.0",
+                "description": "Office supplies",
+                "price": "99.0",
+                "period": None,
+            }
+        ],
+        "payments": [],
+        "notes": [],
+        "attachments": [],
+        "events": [],
+    }
+
+
 @pytest.fixture(name="payment_data")
 def fixture_payment_data() -> dict[str, Any]:
     """Full payment response matching Moneybird OpenAPI payment_response schema."""