statuspro-openapi-client 0.1.0__py3-none-any.whl

statuspro_public_api_client/client_types.py

@@ -0,0 +1,54 @@
+"""Contains some shared types for properties"""
+
+from collections.abc import Mapping, MutableMapping
+from http import HTTPStatus
+from typing import IO, BinaryIO, Literal, TypeVar
+
+from attrs import define
+
+
+class Unset:
+    def __bool__(self) -> Literal[False]:
+        return False
+
+
+UNSET: Unset = Unset()
+
+# The types that `httpx.Client(files=)` can accept, copied from that library.
+FileContent = IO[bytes] | bytes | str
+FileTypes = (
+    # (filename, file (or bytes), content_type)
+    tuple[str | None, FileContent, str | None]
+    # (filename, file (or bytes), content_type, headers)
+    | tuple[str | None, FileContent, str | None, Mapping[str, str]]
+)
+RequestFiles = list[tuple[str, FileTypes]]
+
+
+@define
+class File:
+    """Contains information for file uploads"""
+
+    payload: BinaryIO
+    file_name: str | None = None
+    mime_type: str | None = None
+
+    def to_tuple(self) -> FileTypes:
+        """Return a tuple representation that httpx will accept for multipart/form-data"""
+        return self.file_name, self.payload, self.mime_type
+
+
+T = TypeVar("T")
+
+
+@define
+class Response[T]:
+    """A response from an endpoint"""
+
+    status_code: HTTPStatus
+    content: bytes
+    headers: MutableMapping[str, str]
+    parsed: T | None
+
+
+__all__ = ["UNSET", "File", "FileTypes", "RequestFiles", "Response", "Unset"]

statuspro_public_api_client/domain/__init__.py

@@ -0,0 +1,33 @@
+"""Pydantic domain models for StatusPro entities.
+
+Hand-written domain models representing business entities from the StatusPro API,
+separate from the generated attrs API request/response models. Use these for
+business logic, validation, and ergonomic access to API data.
+
+Example:
+    ```python
+    from statuspro_public_api_client import StatusProClient
+    from statuspro_public_api_client.domain import Order
+
+    async with StatusProClient() as client:
+        orders = await client.orders.list(per_page=50)
+        for order in orders:
+            print(f"{order.name}: {order.status.name}")
+    ```
+"""
+
+from .base import StatusProBaseModel
+from .converters import to_unset, unwrap_unset
+from .order import Customer, Order, OrderStatus, PageMeta
+from .status import Status
+
+__all__ = [
+    "Customer",
+    "Order",
+    "OrderStatus",
+    "PageMeta",
+    "Status",
+    "StatusProBaseModel",
+    "to_unset",
+    "unwrap_unset",
+]

statuspro_public_api_client/domain/base.py

@@ -0,0 +1,117 @@
+"""Base domain model for StatusPro entities.
+
+This module provides the foundation for Pydantic domain models that represent
+business entities from the StatusPro Manufacturing ERP system.
+
+Domain models are separate from the generated API request/response models and
+are optimized for:
+- ETL and data processing
+- Business logic
+- Data validation
+- JSON schema generation
+- Clean, ergonomic APIs
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field
+
+
+class StatusProBaseModel(BaseModel):
+    """Base class for all Pydantic domain models.
+
+    Provides:
+    - Immutability by default (frozen=True)
+    - Automatic validation
+    - JSON schema generation
+    - Easy serialization for ETL
+    - Common timestamp fields
+
+    Example:
+        ```python
+        class OrderDomain(StatusProBaseModel):
+            id: int
+            name: str
+            order_number: str | None = None
+
+            @computed_field
+            @property
+            def display_name(self) -> str:
+                return f"Order {self.name} (#{self.order_number})"
+        ```
+    """
+
+    model_config = ConfigDict(
+        frozen=True,  # Immutable by default
+        validate_assignment=True,  # Validate on updates (if unfrozen)
+        arbitrary_types_allowed=True,  # Allow datetime, etc.
+        str_strip_whitespace=True,  # Clean string inputs
+        json_schema_extra={
+            "source": "StatusPro Manufacturing ERP",
+            "version": "v1",
+        },
+    )
+
+    # Metadata about the source model
+    _source_model: ClassVar[str] = "attrs"
+    _api_version: ClassVar[str] = "v1"
+
+    # Common timestamp fields (most StatusPro entities have these)
+    # Using AwareDatetime to match generated Pydantic models and ensure timezone awareness
+    created_at: AwareDatetime | None = Field(
+        None, description="Timestamp when entity was created"
+    )
+    updated_at: AwareDatetime | None = Field(
+        None, description="Timestamp when entity was last updated"
+    )
+    deleted_at: AwareDatetime | None = Field(
+        None, description="Timestamp when entity was soft-deleted (if applicable)"
+    )
+
+    def model_dump_for_etl(self) -> dict[str, Any]:
+        """Export to ETL-friendly format.
+
+        Removes None values and uses field aliases for cleaner output.
+
+        Returns:
+            Dictionary with all non-None fields
+
+        Example:
+            ```python
+            order = Order(id=123, name="#1188", order_number="1188")
+            data = order.model_dump_for_etl()
+            # {"id": 123, "name": "#1188", "order_number": "1188"}
+            ```
+        """
+        return self.model_dump(exclude_none=True, by_alias=True)
+
+    def to_warehouse_json(self) -> str:
+        """Export as JSON for data warehouse.
+
+        Returns:
+            JSON string with all non-None fields
+
+        Example:
+            ```python
+            order = Order(id=123, name="#1188")
+            json_str = order.to_warehouse_json()
+            # '{"id":123,"name":"#1188"}'
+            ```
+        """
+        return self.model_dump_json(exclude_none=True, by_alias=True)
+
+    def to_dict_with_computed(self) -> dict[str, Any]:
+        """Export including computed fields.
+
+        Unlike model_dump(), this includes @computed_field properties.
+
+        Returns:
+            Dictionary with all fields including computed ones
+        """
+        # Pydantic v2 automatically includes computed fields in model_dump
+        return self.model_dump(mode="python", exclude_none=True)
+
+
+__all__ = ["StatusProBaseModel"]

statuspro_public_api_client/domain/converters.py

@@ -0,0 +1,71 @@
+"""Generic conversion utilities for attrs API models.
+
+These helpers bridge the attrs-based generated models (which use ``UNSET`` for
+unprovided fields) and Pydantic domain models (which use ``None``).
+"""
+
+from __future__ import annotations
+
+from typing import overload
+
+from ..client_types import UNSET, Unset
+
+
+def to_unset[T](value: T | None) -> T | Unset:
+    """Convert None to UNSET sentinel value.
+
+    Useful when building attrs API request models from optional Pydantic fields,
+    where None means "not provided" and should be sent as UNSET to avoid
+    overwriting existing values.
+
+    Args:
+        value: Value that might be None
+
+    Returns:
+        The value unchanged if not None, or UNSET if None
+
+    Example:
+        ```python
+        from statuspro_public_api_client.domain.converters import to_unset
+
+        to_unset(42)  # 42
+        to_unset(None)  # UNSET
+        to_unset("USD")  # "USD"
+        ```
+    """
+    return UNSET if value is None else value
+
+
+@overload
+def unwrap_unset[T](value: T | Unset | None) -> T | None: ...
+
+
+@overload
+def unwrap_unset[T](value: T | Unset | None, default: T) -> T: ...
+
+
+def unwrap_unset[T](value: T | Unset | None, default: T | None = None) -> T | None:
+    """Unwrap an Unset or None sentinel value.
+
+    Args:
+        value: Value that might be Unset or None
+        default: Default value to return if Unset or None
+
+    Returns:
+        The unwrapped value, or default if value is Unset or None. When a
+        non-None default is provided, the return type is narrowed to ``T``
+        (never None).
+
+    Example:
+        ```python
+        from statuspro_public_api_client.client_types import UNSET
+
+        unwrap_unset(42)  # 42
+        unwrap_unset(UNSET)  # None
+        unwrap_unset(UNSET, 0)  # 0
+        unwrap_unset(None, 0)  # 0
+        ```
+    """
+    if value is None or isinstance(value, Unset):
+        return default
+    return value

statuspro_public_api_client/domain/order.py

@@ -0,0 +1,87 @@
+"""Domain models for StatusPro orders.
+
+Hand-written Pydantic models for business logic, separate from the generated
+attrs API models. Shapes mirror the OpenAPI ``Customer``, ``Status``,
+``OrderListItem``, ``OrderResponse``, and ``OrderListMeta`` schemas.
+"""
+
+from __future__ import annotations
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field
+
+
+class _Frozen(BaseModel):
+    """Immutable Pydantic base used for nested types that don't carry timestamps."""
+
+    model_config = ConfigDict(
+        frozen=True,
+        str_strip_whitespace=True,
+        extra="ignore",
+    )
+
+
+class Customer(_Frozen):
+    """Customer details attached to an order."""
+
+    name: str | None = None
+    email: str | None = None
+    locale: str | None = None
+
+
+class OrderStatus(_Frozen):
+    """The status currently set on an order (nested ``Status`` schema).
+
+    Distinct from :class:`Status`, which is a top-level status definition
+    returned by ``/statuses`` and includes ``color`` instead of transition
+    metadata.
+    """
+
+    is_set: bool | None = None
+    code: str | None = Field(None, description="8-char status code, e.g. 'st000002'")
+    name: str | None = None
+    public_name: str | None = None
+    description: str | None = None
+    public: bool | None = None
+    set_at: AwareDatetime | None = None
+    auto_change_at: AwareDatetime | None = None
+
+
+class Order(_Frozen):
+    """An order as returned by ``/orders`` list pages or ``/orders/{id}``."""
+
+    id: int
+    name: str | None = Field(None, description="Display name, e.g. '#1188'")
+    order_number: str | None = None
+    customer: Customer | None = None
+    status: OrderStatus | None = None
+    due_date: AwareDatetime | None = None
+    due_date_to: AwareDatetime | None = None
+    history_count: int | None = Field(
+        None,
+        description="Number of history entries; only present on list responses",
+    )
+
+
+class PageMeta(_Frozen):
+    """Pagination envelope returned alongside list endpoints.
+
+    Matches the StatusPro ``OrderListMeta`` schema. ``current_page`` and
+    ``last_page`` are used by the transport layer to auto-walk pages.
+    """
+
+    current_page: int
+    last_page: int
+    per_page: int
+    total: int
+    from_: int | None = Field(None, alias="from")
+    to: int | None = None
+
+    model_config = ConfigDict(
+        frozen=True,
+        str_strip_whitespace=True,
+        extra="ignore",
+        populate_by_name=True,
+    )
+
+
+__all__ = ["Customer", "Order", "OrderStatus", "PageMeta"]

statuspro_public_api_client/domain/status.py

@@ -0,0 +1,30 @@
+"""Domain model for StatusPro status definitions.
+
+Matches the OpenAPI ``StatusDefinition`` schema (returned by ``/statuses``)
+and is structurally identical to ``ViableStatus`` (returned by
+``/orders/{id}/viable-statuses``).
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Status(BaseModel):
+    """A top-level status definition from the account's status catalog."""
+
+    code: str = Field(..., description="8-char code, e.g. 'st000002'")
+    name: str | None = None
+    description: str | None = None
+    color: str | None = Field(
+        None, description="Display color, either a name (e.g. 'pink') or hex"
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        str_strip_whitespace=True,
+        extra="ignore",
+    )
+
+
+__all__ = ["Status"]

statuspro_public_api_client/errors.py

@@ -0,0 +1,16 @@
+"""Contains shared errors types that can be raised from API functions"""
+
+
+class UnexpectedStatus(Exception):
+    """Raised by api functions when the response status an undocumented status and Client.raise_on_unexpected_status is True"""
+
+    def __init__(self, status_code: int, content: bytes):
+        self.status_code = status_code
+        self.content = content
+
+        super().__init__(
+            f"Unexpected status code: {status_code}\n\nResponse content:\n{content.decode(errors='ignore')}"
+        )
+
+
+__all__ = ["UnexpectedStatus"]

statuspro_public_api_client/helpers/__init__.py

@@ -0,0 +1,21 @@
+"""Ergonomic helper facades for the StatusPro API client.
+
+These classes wrap the generated API with domain-specific methods that reduce
+boilerplate for common workflows. Each helper is accessed as an attribute on
+``StatusProClient`` (e.g. ``client.orders.list(...)``).
+
+Example:
+    >>> async with StatusProClient() as client:
+    ...     orders = await client.orders.list(per_page=50)
+    ...     statuses = await client.statuses.list()
+"""
+
+from statuspro_public_api_client.helpers.base import Base
+from statuspro_public_api_client.helpers.orders import Orders
+from statuspro_public_api_client.helpers.statuses import Statuses
+
+__all__ = [
+    "Base",
+    "Orders",
+    "Statuses",
+]

statuspro_public_api_client/helpers/base.py

@@ -0,0 +1,26 @@
+"""Base class for domain classes."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from statuspro_public_api_client.statuspro_client import StatusProClient
+
+
+class Base:
+    """Base class for all domain classes.
+
+    Provides common functionality and access to the StatusProClient instance.
+
+    Args:
+        client: The StatusProClient instance to use for API calls.
+    """
+
+    def __init__(self, client: StatusProClient) -> None:
+        """Initialize with a client instance.
+
+        Args:
+            client: The StatusProClient instance to use for API calls.
+        """
+        self._client = client

statuspro_public_api_client/helpers/orders.py

@@ -0,0 +1,78 @@
+"""Order helper facade — ergonomic wrappers around the generated order endpoints."""
+
+from __future__ import annotations
+
+import builtins
+from typing import TYPE_CHECKING, Any
+
+from statuspro_public_api_client.helpers.base import Base
+
+if TYPE_CHECKING:
+    from statuspro_public_api_client.domain import Order
+
+
+class Orders(Base):
+    """Ergonomic order operations that return domain ``Order`` models."""
+
+    async def list(
+        self,
+        *,
+        search: str | None = None,
+        status_code: str | None = None,
+        tags: builtins.list[str] | None = None,
+        tags_any: builtins.list[str] | None = None,
+        financial_status: builtins.list[str] | None = None,
+        fulfillment_status: builtins.list[str] | None = None,
+        exclude_cancelled: bool | None = None,
+        due_date_from: str | None = None,
+        due_date_to: str | None = None,
+        page: int | None = None,
+        per_page: int | None = None,
+    ) -> builtins.list[Order]:
+        """List orders. Auto-paginates when ``page`` is not set."""
+        from statuspro_public_api_client.api.orders import list_orders
+        from statuspro_public_api_client.domain import Order
+        from statuspro_public_api_client.utils import unwrap_data
+
+        kwargs: dict[str, Any] = {
+            "client": self._client,
+            "search": search,
+            "status_code": status_code,
+            "tags": tags,
+            "tags_any": tags_any,
+            "financial_status": financial_status,
+            "fulfillment_status": fulfillment_status,
+            "exclude_cancelled": exclude_cancelled,
+            "due_date_from": due_date_from,
+            "due_date_to": due_date_to,
+            "page": page,
+            "per_page": per_page,
+        }
+        kwargs = {k: v for k, v in kwargs.items() if v is not None}
+        response = await list_orders.asyncio_detailed(**kwargs)
+        raw_orders = unwrap_data(response, default=[])
+        return [Order.model_validate(o.to_dict()) for o in raw_orders]
+
+    async def get(self, order_id: int) -> Order:
+        """Get a single order by id."""
+        from statuspro_public_api_client.api.orders import get_order
+        from statuspro_public_api_client.domain import Order
+        from statuspro_public_api_client.models.order_response import OrderResponse
+        from statuspro_public_api_client.utils import unwrap_as
+
+        response = await get_order.asyncio_detailed(client=self._client, order=order_id)
+        raw = unwrap_as(response, OrderResponse)
+        return Order.model_validate(raw.to_dict())
+
+    async def lookup(self, *, number: str, email: str) -> Order:
+        """Look up an order by order number and customer email."""
+        from statuspro_public_api_client.api.orders import lookup_order
+        from statuspro_public_api_client.domain import Order
+        from statuspro_public_api_client.models.order_response import OrderResponse
+        from statuspro_public_api_client.utils import unwrap_as
+
+        response = await lookup_order.asyncio_detailed(
+            client=self._client, number=number, email=email
+        )
+        raw = unwrap_as(response, OrderResponse)
+        return Order.model_validate(raw.to_dict())

statuspro_public_api_client/helpers/statuses.py

@@ -0,0 +1,37 @@
+"""Status helper facade — ergonomic wrappers around the generated status endpoints."""
+
+from __future__ import annotations
+
+import builtins
+from typing import TYPE_CHECKING
+
+from statuspro_public_api_client.helpers.base import Base
+
+if TYPE_CHECKING:
+    from statuspro_public_api_client.domain import Status
+
+
+class Statuses(Base):
+    """Ergonomic status catalog operations."""
+
+    async def list(self) -> builtins.list[Status]:
+        """Return the full status catalog (``/statuses``)."""
+        from statuspro_public_api_client.api.statuses import get_statuses
+        from statuspro_public_api_client.domain import Status
+        from statuspro_public_api_client.utils import unwrap_data
+
+        response = await get_statuses.asyncio_detailed(client=self._client)
+        raw = unwrap_data(response, default=[])
+        return [Status.model_validate(s.to_dict()) for s in raw]
+
+    async def viable_for(self, order_id: int) -> builtins.list[Status]:
+        """Return statuses that are valid transitions from the order's current state."""
+        from statuspro_public_api_client.api.orders import get_viable_statuses
+        from statuspro_public_api_client.domain import Status
+        from statuspro_public_api_client.utils import unwrap_data
+
+        response = await get_viable_statuses.asyncio_detailed(
+            client=self._client, order=order_id
+        )
+        raw = unwrap_data(response, default=[])
+        return [Status.model_validate(s.to_dict()) for s in raw]

statuspro_public_api_client/log_setup.py

@@ -0,0 +1,99 @@
+"""Logging setup utilities for the StatusPro API client.
+
+This module provides logging configuration helpers for the enhanced StatusPro client.
+
+"""
+
+import logging
+import logging.handlers
+from pathlib import Path
+
+
+class InfoToDebugFilter(logging.Filter):
+    """Filter to convert INFO level logs to DEBUG level for specific loggers."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if record.levelno == logging.INFO:
+            record.levelno = logging.DEBUG
+            record.levelname = "DEBUG"
+        return True
+
+
+def setup_logging(
+    log_dir: str = "logs",
+    log_file_prefix: str = "statuspro_client",
+    log_level: int = logging.INFO,
+    console_level: int = logging.INFO,
+    max_bytes: int = 10 * 1024 * 1024,  # 10MB
+    backup_count: int = 5,
+) -> logging.Logger:
+    """Set up logging configuration for the StatusPro client.
+
+    Args:
+        log_dir: Directory to store log files
+        log_file_prefix: Prefix for log file names
+        log_level: Logging level for file handler
+        console_level: Logging level for console handler
+        max_bytes: Maximum size of each log file before rotation
+        backup_count: Number of backup files to keep
+
+    Returns:
+        Configured logger instance
+
+    """
+    # Create log directory if it doesn't exist
+    log_path = Path(log_dir)
+    log_path.mkdir(exist_ok=True)
+
+    # Create logger
+    logger = logging.getLogger("statuspro_client")
+    logger.setLevel(logging.DEBUG)
+
+    # Remove existing handlers to avoid duplicates
+    for handler in logger.handlers[:]:
+        logger.removeHandler(handler)
+
+    # Create formatters
+    detailed_formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(funcName)s:%(lineno)d - %(message)s"
+    )
+    simple_formatter = logging.Formatter("%(asctime)s - %(levelname)s - %(message)s")
+
+    # File handler with rotation
+    log_file = log_path / f"{log_file_prefix}.log"
+    file_handler = logging.handlers.RotatingFileHandler(
+        log_file, maxBytes=max_bytes, backupCount=backup_count
+    )
+    file_handler.setLevel(log_level)
+    file_handler.setFormatter(detailed_formatter)
+    logger.addHandler(file_handler)
+
+    # Console handler
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(console_level)
+    console_handler.setFormatter(simple_formatter)
+    logger.addHandler(console_handler)
+
+    # Set up httpx logger with filter
+    httpx_logger = logging.getLogger("httpx")
+    httpx_logger.setLevel(logging.DEBUG)
+    httpx_logger.addFilter(InfoToDebugFilter())
+
+    logger.info(
+        f"Logging configured - File: {log_file}, Level: {logging.getLevelName(log_level)}"
+    )
+
+    return logger
+
+
+def get_logger(name: str | None = None) -> logging.Logger:
+    """Get a logger instance.
+
+    Args:
+        name: Logger name (defaults to statuspro_client)
+
+    Returns:
+        Logger instance
+
+    """
+    return logging.getLogger(name or "statuspro_client")