ordercloud-python 2026.4.1__py3-none-any.whl

ordercloud/resources/base.py

@@ -0,0 +1,145 @@
+"""Base resource class with shared helpers for OrderCloud API resources."""
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Any, Optional, TypeVar
+
+from pydantic import BaseModel
+
+from ..http import HttpClient
+from ..models.shared import ListPage, Meta
+
+T = TypeVar("T", bound=BaseModel)
+
+__all__ = ["BaseResource", "paginate"]
+
+
+async def paginate(
+    list_method: Callable[..., Awaitable[ListPage[T]]],
+    *args: Any,
+    page_size: int = 100,
+    **kwargs: Any,
+) -> AsyncIterator[T]:
+    """Auto-paginate any list endpoint, yielding individual items.
+
+    Calls ``list_method`` repeatedly, incrementing the page number until
+    all pages have been fetched.  Yields items one at a time.
+
+    Args:
+        list_method: A bound list method (e.g. ``client.products.list``).
+        *args: Positional arguments forwarded to the list method.
+        page_size: Items per page (default 100, the API maximum).
+        **kwargs: Keyword arguments forwarded to the list method.
+
+    Yields:
+        Individual items across all pages.
+
+    Example::
+
+        from ordercloud.resources import paginate
+
+        async for product in paginate(client.products.list, search="widget"):
+            print(product.name)
+    """
+    page = 1
+    kwargs["page_size"] = page_size
+    while True:
+        kwargs["page"] = page
+        result = await list_method(*args, **kwargs)
+        for item in result.items:
+            yield item
+        if page >= result.meta.total_pages:
+            break
+        page += 1
+
+
+class BaseResource:
+    """Base class for OrderCloud API resource clients.
+
+    Provides shared infrastructure used by all resource implementations:
+    HTTP client storage, list-parameter building, response parsing,
+    and model serialisation.
+    """
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    @staticmethod
+    def _build_list_params(
+        *,
+        search: Optional[str] = None,
+        search_on: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        depth: Optional[str] = None,
+        filters: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Build query parameters for a list endpoint.
+
+        Maps snake_case Python parameter names to the camelCase names
+        expected by the OrderCloud API.  Only non-None values are included.
+
+        Args:
+            search: Free-text search term.
+            search_on: Comma-separated field names to search on.
+            sort_by: Field name to sort by (prefix with ``!`` to reverse).
+            page: 1-based page number.
+            page_size: Number of items per page (max 100).
+            depth: Category tree depth (categories only).
+            filters: Arbitrary key/value filters merged into the params.
+
+        Returns:
+            A dict of query parameters ready to pass to the HTTP client.
+        """
+        params: dict[str, Any] = {}
+        if search is not None:
+            params["search"] = search
+        if search_on is not None:
+            params["searchOn"] = search_on
+        if sort_by is not None:
+            params["sortBy"] = sort_by
+        if page is not None:
+            params["page"] = page
+        if page_size is not None:
+            params["pageSize"] = page_size
+        if depth is not None:
+            params["depth"] = depth
+        if filters:
+            params.update(filters)
+        return params
+
+    @staticmethod
+    def _parse_list(
+        data: dict[str, Any], model_cls: type[T], meta_cls: type[Meta] = Meta
+    ) -> ListPage[T]:
+        """Parse a raw JSON dict into a typed ``ListPage``.
+
+        Args:
+            data: Decoded JSON body from a list endpoint response.
+            model_cls: The Pydantic model class for individual items.
+            meta_cls: The metadata class (``Meta`` or ``MetaWithFacets``).
+
+        Returns:
+            A ``ListPage`` containing parsed items and pagination metadata.
+        """
+        return ListPage[model_cls](  # type: ignore[valid-type]
+            items=[model_cls.model_validate(item) for item in data.get("Items", [])],
+            meta=meta_cls.model_validate(data.get("Meta", {})),
+        )
+
+    @staticmethod
+    def _serialize(model: BaseModel | dict[str, Any]) -> dict[str, Any]:
+        """Serialise a Pydantic model or plain dict for an API request body.
+
+        Accepts either a Pydantic ``BaseModel`` instance (serialised with
+        ``exclude_none=True``) or a raw ``dict`` (passed through unchanged).
+
+        Args:
+            model: A Pydantic model instance or a dict.
+
+        Returns:
+            A JSON-serialisable dict.
+        """
+        if isinstance(model, BaseModel):
+            return model.model_dump(by_alias=True, exclude_none=True)
+        return model

ordercloud/resources/bundle_line_items.py

@@ -0,0 +1,59 @@
+# GENERATED by tools/codegen — DO NOT EDIT
+# Source: ordercloud-openapi-v3.json
+"""OrderCloud BundleLineItems API resource."""
+
+from __future__ import annotations
+from typing import Any, Union
+
+from ..models.line_item import BundleItems, LineItem
+from ..models.misc import OrderDirection
+from .base import BaseResource
+
+__all__ = ["BundleLineItemsResource"]
+
+
+class BundleLineItemsResource(BaseResource):
+    """Operations on OrderCloud BundleLineItems."""
+
+    async def create(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        bundle_id: str,
+        bundle_items: Union[BundleItems, dict[str, Any]],
+    ) -> LineItem:
+        """Create a bundle line item
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            bundle_id: ID of the bundle.
+            bundle_items: A ``BundleItems`` model or dict.
+
+        Returns:
+            The LineItem object.
+        """
+        resp = await self._http.post(
+            f"/orders/{direction}/{order_id}/bundles/{bundle_id}",
+            json=self._serialize(bundle_items),
+        )
+        return LineItem(**resp.json())
+
+    async def delete(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        bundle_id: str,
+        bundle_item_id: str,
+    ) -> None:
+        """Delete a bundle line item
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            bundle_id: ID of the bundle.
+            bundle_item_id: ID of the bundle item.
+        """
+        await self._http.delete(
+            f"/orders/{direction}/{order_id}/bundles/{bundle_id}/{bundle_item_id}"
+        )

ordercloud/resources/bundle_subscription_items.py

@@ -0,0 +1,54 @@
+# GENERATED by tools/codegen — DO NOT EDIT
+# Source: ordercloud-openapi-v3.json
+"""OrderCloud BundleSubscriptionItems API resource."""
+
+from __future__ import annotations
+from typing import Any, Union
+
+from ..models.line_item import BundleItems, LineItem
+from .base import BaseResource
+
+__all__ = ["BundleSubscriptionItemsResource"]
+
+
+class BundleSubscriptionItemsResource(BaseResource):
+    """Operations on OrderCloud BundleSubscriptionItems."""
+
+    async def create(
+        self,
+        subscription_id: str,
+        bundle_id: str,
+        bundle_items: Union[BundleItems, dict[str, Any]],
+    ) -> LineItem:
+        """Create a bundle subscription item
+
+        Args:
+            subscription_id: ID of the subscription.
+            bundle_id: ID of the bundle.
+            bundle_items: A ``BundleItems`` model or dict.
+
+        Returns:
+            The LineItem object.
+        """
+        resp = await self._http.post(
+            f"/subscriptions/{subscription_id}/bundles/{bundle_id}",
+            json=self._serialize(bundle_items),
+        )
+        return LineItem(**resp.json())
+
+    async def delete(
+        self,
+        subscription_id: str,
+        bundle_id: str,
+        bundle_item_id: str,
+    ) -> None:
+        """Delete a bundle subscription item
+
+        Args:
+            subscription_id: ID of the subscription.
+            bundle_id: ID of the bundle.
+            bundle_item_id: ID of the bundle item.
+        """
+        await self._http.delete(
+            f"/subscriptions/{subscription_id}/bundles/{bundle_id}/{bundle_item_id}"
+        )

ordercloud/resources/bundles.py

@@ -0,0 +1,278 @@
+# GENERATED by tools/codegen — DO NOT EDIT
+# Source: ordercloud-openapi-v3.json
+"""OrderCloud Bundles API resource."""
+
+from __future__ import annotations
+from typing import Any, Optional, Union
+
+from ..models.assignments import BundleAssignment, BundleProductAssignment
+from ..models.bundle import Bundle
+from ..models.misc import SearchType
+from ..models.shared import ListPage, MetaWithFacets
+from .base import BaseResource
+
+__all__ = ["BundlesResource"]
+
+
+class BundlesResource(BaseResource):
+    """Operations on OrderCloud Bundles."""
+
+    async def list(
+        self,
+        *,
+        catalog_id: Optional[str] = None,
+        category_id: Optional[str] = None,
+        supplier_id: Optional[str] = None,
+        search: Optional[str] = None,
+        search_on: Optional[str] = None,
+        search_type: Optional[SearchType] = None,
+        sort_by: Optional[str] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        filters: Optional[dict[str, Any]] = None,
+    ) -> ListPage[Bundle]:
+        """List bundles
+
+        Args:
+            catalog_id: ID of the catalog.
+            category_id: ID of the category.
+            supplier_id: ID of the supplier.
+            search: Word or phrase to search for.
+            search_on: Comma-delimited list of fields to search on.
+            search_type: Type of search to perform.
+            sort_by: Comma-delimited list of fields to sort by.
+            page: Page of results to return. When paginating through many items (> page 30), we recommend the "Last ID" method, as outlined in the Advanced Querying documentation.
+            page_size: Number of results to return per page.
+            filters: An object or dictionary representing key/value pairs to apply as filters. Valid keys are top-level properties of the returned model or 'xp.???'
+
+        Returns:
+            A paginated list of Bundle objects.
+        """
+        params = self._build_list_params(
+            search=search,
+            search_on=search_on,
+            sort_by=sort_by,
+            page=page,
+            page_size=page_size,
+            filters=filters,
+        )
+        if catalog_id is not None:
+            params["catalogID"] = catalog_id
+        if category_id is not None:
+            params["categoryID"] = category_id
+        if supplier_id is not None:
+            params["supplierID"] = supplier_id
+        if search_type is not None:
+            params["searchType"] = search_type
+        resp = await self._http.get("/bundles", **params)
+        return self._parse_list(resp.json(), Bundle, meta_cls=MetaWithFacets)
+
+    async def create(
+        self,
+        bundle: Union[Bundle, dict[str, Any]],
+    ) -> Bundle:
+        """Create a bundle
+
+        Args:
+            bundle: A ``Bundle`` model or dict. Required fields: Name.
+
+        Returns:
+            The Bundle object.
+        """
+        resp = await self._http.post("/bundles", json=self._serialize(bundle))
+        return Bundle(**resp.json())
+
+    async def get(
+        self,
+        bundle_id: str,
+    ) -> Bundle:
+        """Retrieve a bundle
+
+        Args:
+            bundle_id: ID of the bundle.
+
+        Returns:
+            The Bundle object.
+        """
+        resp = await self._http.get(f"/bundles/{bundle_id}")
+        return Bundle(**resp.json())
+
+    async def save(
+        self,
+        bundle_id: str,
+        bundle: Union[Bundle, dict[str, Any]],
+    ) -> Bundle:
+        """Create or update a bundle
+
+        Args:
+            bundle_id: ID of the bundle.
+            bundle: A ``Bundle`` model or dict. Required fields: Name.
+
+        Returns:
+            The Bundle object.
+        """
+        resp = await self._http.put(
+            f"/bundles/{bundle_id}",
+            json=self._serialize(bundle),
+        )
+        return Bundle(**resp.json())
+
+    async def delete(
+        self,
+        bundle_id: str,
+    ) -> None:
+        """Delete a bundle
+
+        Args:
+            bundle_id: ID of the bundle.
+        """
+        await self._http.delete(f"/bundles/{bundle_id}")
+
+    async def patch(
+        self,
+        bundle_id: str,
+        partial: dict[str, Any],
+    ) -> Bundle:
+        """Partially update a bundle
+
+        Args:
+            bundle_id: ID of the bundle.
+            partial: A dict of fields to update.
+
+        Returns:
+            The Bundle object.
+        """
+        resp = await self._http.patch(f"/bundles/{bundle_id}", json=partial)
+        return Bundle(**resp.json())
+
+    async def delete_assignment(
+        self,
+        bundle_id: str,
+        buyer_id: str,
+        *,
+        user_id: Optional[str] = None,
+        user_group_id: Optional[str] = None,
+        seller_id: Optional[str] = None,
+    ) -> None:
+        """Delete a bundle assignment
+
+        Args:
+            bundle_id: ID of the bundle.
+            buyer_id: ID of the buyer.
+            user_id: ID of the user.
+            user_group_id: ID of the user group.
+            seller_id: ID of the seller.
+        """
+        _params: dict[str, Any] = {}
+        if user_id is not None:
+            _params["userID"] = user_id
+        if user_group_id is not None:
+            _params["userGroupID"] = user_group_id
+        if seller_id is not None:
+            _params["sellerID"] = seller_id
+        await self._http.delete(f"/bundles/{bundle_id}/assignments/{buyer_id}", **_params)
+
+    async def delete_product_assignment(
+        self,
+        bundle_id: str,
+        product_id: str,
+    ) -> None:
+        """Delete a bundle product assignment
+
+        Args:
+            bundle_id: ID of the bundle.
+            product_id: ID of the product.
+        """
+        await self._http.delete(f"/bundles/{bundle_id}/productassignments/{product_id}")
+
+    async def list_assignments(
+        self,
+        *,
+        bundle_id: Optional[str] = None,
+        buyer_id: Optional[str] = None,
+        user_group_id: Optional[str] = None,
+        level: Optional[str] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+    ) -> ListPage[BundleAssignment]:
+        """List bundle assignments
+
+        Args:
+            bundle_id: ID of the bundle.
+            buyer_id: ID of the buyer.
+            user_group_id: ID of the user group.
+            level: Level of the bundle assignment. Possible values: Group, Company, BuyerGroup.
+            page: Page of results to return. When paginating through many items (> page 30), we recommend the "Last ID" method, as outlined in the Advanced Querying documentation.
+            page_size: Number of results to return per page.
+
+        Returns:
+            A paginated list of BundleAssignment objects.
+        """
+        params = self._build_list_params(
+            page=page,
+            page_size=page_size,
+        )
+        if bundle_id is not None:
+            params["bundleID"] = bundle_id
+        if buyer_id is not None:
+            params["buyerID"] = buyer_id
+        if user_group_id is not None:
+            params["userGroupID"] = user_group_id
+        if level is not None:
+            params["level"] = level
+        resp = await self._http.get("/bundles/assignments", **params)
+        return self._parse_list(resp.json(), BundleAssignment)
+
+    async def save_assignment(
+        self,
+        bundle_assignment: Union[BundleAssignment, dict[str, Any]],
+    ) -> None:
+        """Create or update a bundle assignment
+
+        Args:
+            bundle_assignment: A ``BundleAssignment`` model or dict. Required fields: BundleID, BuyerID.
+        """
+        await self._http.post("/bundles/assignments", json=self._serialize(bundle_assignment))
+
+    async def list_product_assignments(
+        self,
+        *,
+        bundle_id: Optional[str] = None,
+        product_id: Optional[str] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+    ) -> ListPage[BundleProductAssignment]:
+        """List bundle product assignments
+
+        Args:
+            bundle_id: ID of the bundle.
+            product_id: ID of the product.
+            page: Page of results to return. When paginating through many items (> page 30), we recommend the "Last ID" method, as outlined in the Advanced Querying documentation.
+            page_size: Number of results to return per page.
+
+        Returns:
+            A paginated list of BundleProductAssignment objects.
+        """
+        params = self._build_list_params(
+            page=page,
+            page_size=page_size,
+        )
+        if bundle_id is not None:
+            params["bundleID"] = bundle_id
+        if product_id is not None:
+            params["productID"] = product_id
+        resp = await self._http.get("/bundles/productassignments", **params)
+        return self._parse_list(resp.json(), BundleProductAssignment)
+
+    async def save_product_assignment(
+        self,
+        bundle_product_assignment: Union[BundleProductAssignment, dict[str, Any]],
+    ) -> None:
+        """Create or update a bundle product assignment
+
+        Args:
+            bundle_product_assignment: A ``BundleProductAssignment`` model or dict. Required fields: ProductID, BundleID, Required.
+        """
+        await self._http.post(
+            "/bundles/productassignments", json=self._serialize(bundle_product_assignment)
+        )

ordercloud/resources/buyer_groups.py

@@ -0,0 +1,128 @@
+# GENERATED by tools/codegen — DO NOT EDIT
+# Source: ordercloud-openapi-v3.json
+"""OrderCloud BuyerGroups API resource."""
+
+from __future__ import annotations
+from typing import Any, Optional, Union
+
+from ..models.buyer import BuyerGroup
+from ..models.shared import ListPage
+from .base import BaseResource
+
+__all__ = ["BuyerGroupsResource"]
+
+
+class BuyerGroupsResource(BaseResource):
+    """Operations on OrderCloud BuyerGroups."""
+
+    async def list(
+        self,
+        *,
+        search: Optional[str] = None,
+        search_on: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        filters: Optional[dict[str, Any]] = None,
+    ) -> ListPage[BuyerGroup]:
+        """List buyer groups
+
+        Args:
+            search: Word or phrase to search for.
+            search_on: Comma-delimited list of fields to search on.
+            sort_by: Comma-delimited list of fields to sort by.
+            page: Page of results to return. When paginating through many items (> page 30), we recommend the "Last ID" method, as outlined in the Advanced Querying documentation.
+            page_size: Number of results to return per page.
+            filters: An object or dictionary representing key/value pairs to apply as filters. Valid keys are top-level properties of the returned model or 'xp.???'
+
+        Returns:
+            A paginated list of BuyerGroup objects.
+        """
+        params = self._build_list_params(
+            search=search,
+            search_on=search_on,
+            sort_by=sort_by,
+            page=page,
+            page_size=page_size,
+            filters=filters,
+        )
+        resp = await self._http.get("/buyergroups", **params)
+        return self._parse_list(resp.json(), BuyerGroup)
+
+    async def create(
+        self,
+        buyer_group: Union[BuyerGroup, dict[str, Any]],
+    ) -> BuyerGroup:
+        """Create a buyer group
+
+        Args:
+            buyer_group: A ``BuyerGroup`` model or dict. Required fields: Name.
+
+        Returns:
+            The BuyerGroup object.
+        """
+        resp = await self._http.post("/buyergroups", json=self._serialize(buyer_group))
+        return BuyerGroup(**resp.json())
+
+    async def get(
+        self,
+        buyer_group_id: str,
+    ) -> BuyerGroup:
+        """Retrieve a buyer group
+
+        Args:
+            buyer_group_id: ID of the buyer group.
+
+        Returns:
+            The BuyerGroup object.
+        """
+        resp = await self._http.get(f"/buyergroups/{buyer_group_id}")
+        return BuyerGroup(**resp.json())
+
+    async def save(
+        self,
+        buyer_group_id: str,
+        buyer_group: Union[BuyerGroup, dict[str, Any]],
+    ) -> BuyerGroup:
+        """Create or update a buyer group
+
+        Args:
+            buyer_group_id: ID of the buyer group.
+            buyer_group: A ``BuyerGroup`` model or dict. Required fields: Name.
+
+        Returns:
+            The BuyerGroup object.
+        """
+        resp = await self._http.put(
+            f"/buyergroups/{buyer_group_id}",
+            json=self._serialize(buyer_group),
+        )
+        return BuyerGroup(**resp.json())
+
+    async def delete(
+        self,
+        buyer_group_id: str,
+    ) -> None:
+        """Delete a buyer group
+
+        Args:
+            buyer_group_id: ID of the buyer group.
+        """
+        await self._http.delete(f"/buyergroups/{buyer_group_id}")
+
+    async def patch(
+        self,
+        buyer_group_id: str,
+        partial: dict[str, Any],
+    ) -> BuyerGroup:
+        """Partially update a buyer group
+
+        Args:
+            buyer_group_id: ID of the buyer group.
+            partial: A dict of fields to update.
+
+        Returns:
+            The BuyerGroup object.
+        """
+        resp = await self._http.patch(f"/buyergroups/{buyer_group_id}", json=partial)
+        return BuyerGroup(**resp.json())