plentymarkets-api-client 0.1.2__py3-none-any.whl

plentymarkets/__init__.py

@@ -0,0 +1,19 @@
+from .client import PlentyClient
+from ._types import (
+    ContactCreatePayload,
+    ContactUpdatePayload,
+    ItemCreatePayload,
+    ItemUpdatePayload,
+    OrderCreatePayload,
+    StockCorrectionPayload,
+)
+
+__all__ = [
+    "PlentyClient",
+    "OrderCreatePayload",
+    "ItemCreatePayload",
+    "ItemUpdatePayload",
+    "StockCorrectionPayload",
+    "ContactCreatePayload",
+    "ContactUpdatePayload",
+]

plentymarkets/_exceptions.py

@@ -0,0 +1,31 @@
+class PlentyError(Exception):
+    """Base exception for all plentymarkets client errors."""
+
+
+class AuthError(PlentyError):
+    """Raised on 401 responses or when login credentials are rejected."""
+
+
+class NotFoundError(PlentyError):
+    """Raised on 404 responses."""
+
+
+class RateLimitError(PlentyError):
+    """Raised on 429 responses.
+
+    Attributes:
+        retry_after: Seconds to wait before retrying, taken from the
+            ``Retry-After`` response header. ``0`` if the header is absent.
+    """
+
+    def __init__(self, message: str, retry_after: int = 0) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class ServerError(PlentyError):
+    """Raised on 5xx responses."""
+
+
+class ConnectionError(PlentyError):
+    """Raised when the network is unreachable, DNS fails, or a timeout occurs."""

plentymarkets/_session.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+_JsonDict = dict[str, Any]
+
+import httpx
+
+from ._exceptions import (
+    AuthError,
+    ConnectionError,
+    NotFoundError,
+    PlentyError,
+    RateLimitError,
+    ServerError,
+)
+
+_REFRESH_BUFFER_SECONDS = 60
+
+
+class _Session:
+    """Manages the httpx client, login state, and token lifecycle.
+
+    Args:
+        base_url: PlentyMarkets shop base URL, e.g. ``https://your-shop.plentymarkets.com``.
+        username: PlentyMarkets back-end user e-mail.
+        password: PlentyMarkets back-end user password.
+        client: Shared ``httpx.AsyncClient`` instance.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        username: str,
+        password: str,
+        client: httpx.AsyncClient,
+    ) -> None:
+        stripped = base_url.rstrip("/")
+        if "/rest" in stripped.split("//", 1)[-1]:
+            raise ValueError(
+                f"base_url must be the shop root without '/rest', got: {base_url!r}. "
+                "Example: 'https://your-shop.plentymarkets.com'"
+            )
+        self._base_url = stripped
+        self._username = username
+        self._password = password
+        self._client = client
+        self._access_token: str | None = None
+        self._token_expiry: datetime | None = None
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response, path: str = "/rest/login") -> None:
+        """Map HTTP error responses to PlentyError subclasses.
+
+        Args:
+            response: The httpx response to check.
+            path: Path string used in error messages.
+
+        Raises:
+            AuthError: On 401 responses.
+            NotFoundError: On 404 responses.
+            RateLimitError: On 429 responses.
+            ServerError: On 5xx responses.
+        """
+        if response.status_code == 401:
+            raise AuthError(f"Authentication failed: {path}")
+        if response.status_code == 404:
+            raise NotFoundError(f"{path} returned 404")
+        if response.status_code == 429:
+            retry_after = int(response.headers.get("Retry-After", 0))
+            raise RateLimitError("Rate limit exceeded", retry_after=retry_after)
+        if response.status_code >= 500:
+            raise ServerError(f"Server error {response.status_code}: {path}")
+
+    def _is_token_expiring(self) -> bool:
+        """Return True if the token is absent or within the refresh buffer window.
+
+        Returns:
+            True when re-authentication is required before the next request.
+        """
+        if self._access_token is None or self._token_expiry is None:
+            return True
+        return datetime.now(tz=timezone.utc) >= self._token_expiry - timedelta(
+            seconds=_REFRESH_BUFFER_SECONDS
+        )
+
+    async def login(self) -> None:
+        """Authenticate and store the access token.
+
+        Raises:
+            AuthError: If the server rejects the credentials (HTTP 401).
+            ServerError: On 5xx responses from the login endpoint.
+            RateLimitError: On 429 responses from the login endpoint.
+            ConnectionError: On network failures reaching the login endpoint.
+        """
+        try:
+            response = await self._client.post(
+                f"{self._base_url}/rest/login",
+                json={"username": self._username, "password": self._password},
+            )
+        except (httpx.ConnectError, httpx.TimeoutException) as exc:
+            raise ConnectionError(str(exc)) from exc
+        self._raise_for_status(response, "/rest/login")
+        if response.status_code >= 400:
+            raise PlentyError(f"Login error {response.status_code}")
+        data = response.json()
+        self._access_token = data["accessToken"]
+        self._token_expiry = datetime.now(tz=timezone.utc) + timedelta(
+            seconds=data["expiresIn"]
+        )
+
+    async def logout(self) -> None:
+        """Invalidate the current session token on the server and clear local state.
+
+        If there is no active token, this method is a no-op and makes no network
+        calls. Local state is always cleared, even if the DELETE request fails.
+        """
+        if self._access_token is None:
+            return
+        try:
+            await self._client.delete(
+                f"{self._base_url}/rest/login",
+                headers={"Authorization": f"Bearer {self._access_token}"},
+            )
+        finally:
+            self._access_token = None
+            self._token_expiry = None
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> _JsonDict:
+        """Send an authenticated HTTP request, refreshing the token if needed.
+
+        Args:
+            method: HTTP method (``GET``, ``POST``, ``PUT``, ``DELETE``).
+            path: URL path appended to ``base_url``, e.g. ``/rest/orders/1``.
+            **kwargs: Extra arguments forwarded to ``httpx.AsyncClient.request``.
+
+        Returns:
+            Parsed JSON response body, or ``{}`` for empty responses (HTTP 204).
+
+        Raises:
+            AuthError: On persistent 401 after one re-login attempt.
+            NotFoundError: On HTTP 404.
+            RateLimitError: On HTTP 429.
+            ServerError: On HTTP 5xx.
+            ConnectionError: On network-level failures.
+        """
+        if self._is_token_expiring():
+            await self.login()
+
+        headers = kwargs.pop("headers", {})
+        headers["Authorization"] = f"Bearer {self._access_token}"
+
+        try:
+            response = await self._client.request(
+                method,
+                f"{self._base_url}{path}",
+                headers=headers,
+                **kwargs,
+            )
+        except (httpx.ConnectError, httpx.TimeoutException) as exc:
+            raise ConnectionError(str(exc)) from exc
+
+        if response.status_code == 401:
+            await self.login()
+            headers["Authorization"] = f"Bearer {self._access_token}"
+            try:
+                response = await self._client.request(
+                    method,
+                    f"{self._base_url}{path}",
+                    headers=headers,
+                    **kwargs,
+                )
+            except (httpx.ConnectError, httpx.TimeoutException) as exc:
+                raise ConnectionError(str(exc)) from exc
+            if response.status_code == 401:
+                raise AuthError("Authentication failed after token refresh")
+
+        if response.status_code == 404:
+            raise NotFoundError(f"{method} {path} returned 404")
+        if response.status_code == 429:
+            retry_after = int(response.headers.get("Retry-After", 0))
+            raise RateLimitError("Rate limit exceeded", retry_after=retry_after)
+        if response.status_code >= 500:
+            raise ServerError(f"Server error {response.status_code}: {method} {path}")
+        if response.status_code >= 400:
+            raise PlentyError(f"Client error {response.status_code}: {method} {path}")
+
+        response.raise_for_status()
+        if not response.content:
+            return {}
+        return response.json()
+
+    async def get(self, path: str, **kwargs: Any) -> _JsonDict:
+        """Send an authenticated GET request.
+
+        Args:
+            path: URL path appended to ``base_url``.
+            **kwargs: Extra arguments forwarded to ``httpx.AsyncClient.request``.
+
+        Returns:
+            Parsed JSON response body.
+        """
+        return await self._request("GET", path, **kwargs)
+
+    async def post(self, path: str, **kwargs: Any) -> _JsonDict:
+        """Send an authenticated POST request.
+
+        Args:
+            path: URL path appended to ``base_url``.
+            **kwargs: Extra arguments forwarded to ``httpx.AsyncClient.request``.
+
+        Returns:
+            Parsed JSON response body.
+        """
+        return await self._request("POST", path, **kwargs)
+
+    async def put(self, path: str, **kwargs: Any) -> _JsonDict:
+        """Send an authenticated PUT request.
+
+        Args:
+            path: URL path appended to ``base_url``.
+            **kwargs: Extra arguments forwarded to ``httpx.AsyncClient.request``.
+
+        Returns:
+            Parsed JSON response body.
+        """
+        return await self._request("PUT", path, **kwargs)
+
+    async def delete(self, path: str, **kwargs: Any) -> _JsonDict:
+        """Send an authenticated DELETE request.
+
+        Args:
+            path: URL path appended to ``base_url``.
+            **kwargs: Extra arguments forwarded to ``httpx.AsyncClient.request``.
+
+        Returns:
+            Parsed JSON response body.
+        """
+        return await self._request("DELETE", path, **kwargs)

plentymarkets/_types.py

@@ -0,0 +1,277 @@
+"""TypedDict definitions for PlentyMarkets API request payloads.
+
+Import these when constructing payloads to get IDE autocomplete and
+static type checking. At runtime they are plain dicts — no overhead.
+
+Example::
+
+    from plentymarkets._types import OrderCreatePayload
+
+    payload: OrderCreatePayload = {"typeId": 1, "plentyId": 12345}
+    order = await client.orders.create(payload)
+"""
+
+from typing import NotRequired, Required, TypedDict
+
+
+# ---------------------------------------------------------------------------
+# Orders  (/rest/orders)
+# ---------------------------------------------------------------------------
+
+
+class OrderCreatePayload(TypedDict, total=False):
+    """Payload for :meth:`OrdersModule.create` (``POST /rest/orders``).
+
+    Keys:
+        typeId: Order type ID. **Required.**
+            1=sales order, 2=delivery order, 3=returns, 4=credit note,
+            5=warranty, 6=repair, 7=offer, 8=advance order, 9=multi-order.
+        plentyId: Client (store) ID the order belongs to. **Required.**
+        statusId: Numeric order status ID (e.g. ``3.0`` = waiting for payment,
+            ``5.0`` = cleared for shipping). Decimal part is used for
+            sub-statuses.
+        ownerId: User ID of the order owner.
+        lockStatus: Lock state of the order. ``"unlocked"`` or ``"locked"``.
+        orderItems: List of order item dicts. Each item should include
+            ``typeId``, ``itemVariationId``, ``quantity``, and ``amounts``.
+        properties: List of order property dicts, each with ``typeId`` and
+            ``value``.
+        addressRelations: List of address relation dicts. Each entry requires
+            ``typeId`` (1=billing, 2=delivery) and ``addressId``.
+        relations: List of relation dicts, each with ``referenceType``,
+            ``referenceId``, and ``relation``.
+    """
+
+    typeId: Required[int]
+    plentyId: Required[int]
+    statusId: NotRequired[float]
+    ownerId: NotRequired[int]
+    lockStatus: NotRequired[str]
+    orderItems: NotRequired[list[dict]]
+    properties: NotRequired[list[dict]]
+    addressRelations: NotRequired[list[dict]]
+    relations: NotRequired[list[dict]]
+
+
+# ---------------------------------------------------------------------------
+# Items  (/rest/items)
+# ---------------------------------------------------------------------------
+
+
+class ItemCreatePayload(TypedDict, total=False):
+    """Payload for :meth:`ItemsModule.create` (``POST /rest/items``).
+
+    Keys:
+        position: Display position in item lists.
+        stockType: Stock type. 0=stocked, 1=production, 2=colli,
+            3=special order.
+        storeSpecial: Special shop display flag. 0=none, 1=special offer,
+            2=new item, 3=top item.
+        ownerId: User ID of the item owner.
+        manufacturerId: Manufacturer ID.
+        producingCountryId: Country of origin ID (ISO country ID).
+        vatId: VAT configuration ID.
+        condition: Item condition. 0=new, 1=used, 2=refurbished,
+            3=new with original packaging, 4=new with defects, 5=B-stock.
+        conditionApi: Condition value exposed via marketplace APIs
+            (0=new, 1=used, 2=not specified, 3=defective, 4=refurbished).
+        customsTariffNumber: Harmonized System (HS) customs tariff code.
+        revenueAccount: Revenue account number for accounting.
+        couponRestriction: 0=allow all, 1=forbid all, 2=allow coupons only.
+        isSubscribable: Whether the item supports subscription ordering.
+        isShippingPackage: Whether the item ships as a package unit.
+        flagOne: Item flag 1 (shop-specific integer tag).
+        flagTwo: Item flag 2 (shop-specific integer tag).
+        ageRestriction: Age restriction in years. Common values: 0, 6, 12,
+            14, 16, 18, 50.
+        itemType: Item type string. ``"Default"``, ``"Bundle"``,
+            or ``"BundleItem"``.
+        amazonFbaPlatform: Amazon FBA platform. 0=none, 1=AMAZON_EU,
+            2=AMAZON_FE, 3=AMAZON_NA.
+        isShippableByAmazon: Whether Amazon is allowed to fulfil this item.
+        amazonProductType: Amazon browse-node / product type number.
+        ebayPresetId: eBay listing preset ID.
+        ebayCategory: Primary eBay category ID.
+        ebayCategory2: Secondary eBay category ID.
+        rakutenCategoryId: Rakuten product category ID.
+        variations: List of variation dicts. Provide at least one variation
+            with ``isMain: true`` to create a usable item.
+    """
+
+    position: NotRequired[int]
+    stockType: NotRequired[int]
+    storeSpecial: NotRequired[int]
+    ownerId: NotRequired[int]
+    manufacturerId: NotRequired[int]
+    producingCountryId: NotRequired[int]
+    vatId: NotRequired[int]
+    condition: NotRequired[int]
+    conditionApi: NotRequired[int]
+    customsTariffNumber: NotRequired[str]
+    revenueAccount: NotRequired[int]
+    couponRestriction: NotRequired[int]
+    isSubscribable: NotRequired[bool]
+    isShippingPackage: NotRequired[bool]
+    flagOne: NotRequired[int]
+    flagTwo: NotRequired[int]
+    ageRestriction: NotRequired[int]
+    itemType: NotRequired[str]
+    amazonFbaPlatform: NotRequired[int]
+    isShippableByAmazon: NotRequired[bool]
+    amazonProductType: NotRequired[int]
+    ebayPresetId: NotRequired[int]
+    ebayCategory: NotRequired[int]
+    ebayCategory2: NotRequired[int]
+    rakutenCategoryId: NotRequired[int]
+    variations: NotRequired[list[dict]]
+
+
+class ItemUpdatePayload(TypedDict, total=False):
+    """Payload for :meth:`ItemsModule.update` (``PUT /rest/items/{itemId}``).
+
+    All keys are optional — only the fields provided are updated.
+
+    Keys:
+        position: Display position in item lists.
+        stockType: Stock type. 0=stocked, 1=production, 2=colli,
+            3=special order.
+        storeSpecial: Special shop display flag.
+        ownerId: User ID of the item owner.
+        manufacturerId: Manufacturer ID.
+        producingCountryId: Country of origin ID.
+        vatId: VAT configuration ID.
+        condition: Item condition (0–5).
+        conditionApi: Marketplace condition value (0–4).
+        customsTariffNumber: HS / customs tariff code.
+        revenueAccount: Revenue account number.
+        couponRestriction: 0=allow all, 1=forbid all, 2=allow coupons only.
+        isSubscribable: Whether the item supports subscription ordering.
+        isShippingPackage: Whether the item ships as a package unit.
+        flagOne: Item flag 1.
+        flagTwo: Item flag 2.
+        ageRestriction: Age restriction in years.
+        itemType: ``"Default"``, ``"Bundle"``, or ``"BundleItem"``.
+        amazonFbaPlatform: 0=none, 1=AMAZON_EU, 2=AMAZON_FE, 3=AMAZON_NA.
+        isShippableByAmazon: Whether Amazon can fulfil this item.
+        amazonProductType: Amazon product type number.
+        ebayPresetId: eBay listing preset ID.
+        ebayCategory: Primary eBay category ID.
+        ebayCategory2: Secondary eBay category ID.
+        rakutenCategoryId: Rakuten product category ID.
+    """
+
+    position: NotRequired[int]
+    stockType: NotRequired[int]
+    storeSpecial: NotRequired[int]
+    ownerId: NotRequired[int]
+    manufacturerId: NotRequired[int]
+    producingCountryId: NotRequired[int]
+    vatId: NotRequired[int]
+    condition: NotRequired[int]
+    conditionApi: NotRequired[int]
+    customsTariffNumber: NotRequired[str]
+    revenueAccount: NotRequired[int]
+    couponRestriction: NotRequired[int]
+    isSubscribable: NotRequired[bool]
+    isShippingPackage: NotRequired[bool]
+    flagOne: NotRequired[int]
+    flagTwo: NotRequired[int]
+    ageRestriction: NotRequired[int]
+    itemType: NotRequired[str]
+    amazonFbaPlatform: NotRequired[int]
+    isShippableByAmazon: NotRequired[bool]
+    amazonProductType: NotRequired[int]
+    ebayPresetId: NotRequired[int]
+    ebayCategory: NotRequired[int]
+    ebayCategory2: NotRequired[int]
+    rakutenCategoryId: NotRequired[int]
+
+
+# ---------------------------------------------------------------------------
+# Stock  (/rest/stock/warehouses/{warehouseId}/stock/correction)
+# ---------------------------------------------------------------------------
+
+
+class StockCorrectionPayload(TypedDict):
+    """Payload for :meth:`StockModule.correct`
+    (``PUT /rest/stock/warehouses/{warehouseId}/stock/correction``).
+
+    Keys:
+        variationId: Variation ID whose stock should be corrected. **Required.**
+        quantity: New absolute stock quantity after correction. **Required.**
+            Positive values add stock; the API replaces the current level.
+        reasonId: Correction reason ID. **Required.** Common values:
+            301=stock correction, 304=incoming items, 305=outgoing items,
+            309=returns.
+        warehouseLocationId: Storage location ID within the warehouse.
+            **Required.** Use ``0`` for the warehouse default location.
+    """
+
+    variationId: int
+    quantity: float
+    reasonId: int
+    warehouseLocationId: int
+
+
+# ---------------------------------------------------------------------------
+# Contacts  (/rest/accounts/contacts)
+# ---------------------------------------------------------------------------
+
+
+class ContactCreatePayload(TypedDict, total=False):
+    """Payload for :meth:`ContactsModule.create`
+    (``POST /rest/accounts/contacts``).
+
+    Keys:
+        typeId: Contact type. 1=customer, 2=interested party, 3=sales rep,
+            4=supplier, 5=manufacturer, 6=partner.
+        referrerId: Sales referrer ID (float, links to the referrer table).
+        title: Title or form of address string (e.g. ``"Dr."``).
+        firstName: Contact first name.
+        lastName: Contact last name.
+        email: Primary e-mail address.
+        gender: Gender string. ``"male"``, ``"female"``, or ``"diverse"``.
+        lang: Two-letter ISO language code for the contact's preferred
+            language (e.g. ``"de"``, ``"en"``).
+        plentyId: Client (store) ID the contact belongs to.
+        options: List of contact option dicts. Each option requires
+            ``typeId`` (1=telephone, 2=email, 3=messenger, 4=marketplace),
+            ``subTypeId``, ``value``, and ``priority``.
+    """
+
+    typeId: NotRequired[int]
+    referrerId: NotRequired[float]
+    title: NotRequired[str]
+    firstName: NotRequired[str]
+    lastName: NotRequired[str]
+    email: NotRequired[str]
+    gender: NotRequired[str]
+    lang: NotRequired[str]
+    plentyId: NotRequired[int]
+    options: NotRequired[list[dict]]
+
+
+class ContactUpdatePayload(TypedDict, total=False):
+    """Payload for :meth:`ContactsModule.update`
+    (``PUT /rest/accounts/contacts/{contactId}``).
+
+    All keys are optional — only the fields provided are updated.
+
+    Keys:
+        title: Title or form of address string.
+        firstName: Contact first name.
+        lastName: Contact last name.
+        email: Primary e-mail address.
+        gender: Gender string. ``"male"``, ``"female"``, or ``"diverse"``.
+        lang: Two-letter ISO language code.
+        options: List of contact option dicts (typeId, subTypeId, value,
+            priority). Replaces all existing options of the provided types.
+    """
+
+    title: NotRequired[str]
+    firstName: NotRequired[str]
+    lastName: NotRequired[str]
+    email: NotRequired[str]
+    gender: NotRequired[str]
+    lang: NotRequired[str]
+    options: NotRequired[list[dict]]

plentymarkets/client.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import httpx
+
+from ._session import _Session
+from .modules.contacts import ContactsModule
+from .modules.items import ItemsModule
+from .modules.orders import OrdersModule
+from .modules.stock import StockModule
+
+
+class PlentyClient:
+    """Async client for the PlentyMarkets REST API.
+
+    Use as an async context manager (recommended) or call ``login()``/``aclose()``
+    manually.
+
+    Args:
+        base_url: Shop base URL, e.g. ``https://your-shop.plentymarkets.com``.
+        username: PlentyMarkets back-end user e-mail.
+        password: PlentyMarkets back-end user password.
+
+    Example::
+
+        async with PlentyClient(
+            base_url="https://your-shop.plentymarkets.com",
+            username="user@example.com",
+            password="secret",
+        ) as client:
+            order = await client.orders.get(42)
+    """
+
+    def __init__(self, base_url: str, username: str, password: str) -> None:
+        self._httpx_client = httpx.AsyncClient()
+        self._session = _Session(base_url, username, password, self._httpx_client)
+        self._orders: OrdersModule | None = None
+        self._items: ItemsModule | None = None
+        self._stock: StockModule | None = None
+        self._contacts: ContactsModule | None = None
+
+    def __repr__(self) -> str:
+        authenticated = self._session._access_token is not None
+        return (
+            f"PlentyClient(base_url={self._session._base_url!r}, "
+            f"authenticated={authenticated})"
+        )
+
+    async def __aenter__(self) -> PlentyClient:
+        await self.login()
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        try:
+            await self.logout()
+        finally:
+            await self.aclose()
+
+    async def login(self) -> None:
+        """Authenticate and acquire an access token."""
+        await self._session.login()
+
+    async def logout(self) -> None:
+        """Invalidate the current token on the server and clear local state."""
+        await self._session.logout()
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._httpx_client.aclose()
+
+    @property
+    def orders(self) -> OrdersModule:
+        """Access the Orders module (``/rest/orders``)."""
+        if self._orders is None:
+            self._orders = OrdersModule(self._session)
+        return self._orders
+
+    @property
+    def items(self) -> ItemsModule:
+        """Access the Items module (``/rest/items``)."""
+        if self._items is None:
+            self._items = ItemsModule(self._session)
+        return self._items
+
+    @property
+    def stock(self) -> StockModule:
+        """Access the Stock module (``/rest/stock``)."""
+        if self._stock is None:
+            self._stock = StockModule(self._session)
+        return self._stock
+
+    @property
+    def contacts(self) -> ContactsModule:
+        """Access the Contacts module (``/rest/accounts/contacts``)."""
+        if self._contacts is None:
+            self._contacts = ContactsModule(self._session)
+        return self._contacts