miso-client 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

miso_client/__init__.py

@@ -27,6 +27,9 @@ from .models.config import (
     UserInfo,
 )
 from .models.error_response import ErrorResponse
+from .models.filter import FilterBuilder, FilterOperator, FilterOption, FilterQuery
+from .models.pagination import Meta, PaginatedListResponse
+from .models.sort import SortOption
 from .services.auth import AuthService
 from .services.cache import CacheService
 from .services.encryption import EncryptionService
@@ -35,10 +38,19 @@ from .services.permission import PermissionService
 from .services.redis import RedisService
 from .services.role import RoleService
 from .utils.config_loader import load_config
+from .utils.error_utils import handle_api_error_snake_case, transform_error_to_snake_case
+from .utils.filter import apply_filters, build_query_string, parse_filter_params
 from .utils.http_client import HttpClient
 from .utils.internal_http_client import InternalHttpClient
+from .utils.pagination import (
+    apply_pagination_to_array,
+    create_meta_object,
+    create_paginated_list_response,
+    parse_pagination_params,
+)
+from .utils.sort import build_sort_string, parse_sort_params
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 __author__ = "AI Fabrix Team"
 __license__ = "MIT"
 
@@ -491,6 +503,32 @@ __all__ = [
     "PerformanceMetrics",
     "ClientLoggingOptions",
     "ErrorResponse",
+    # Pagination models
+    "Meta",
+    "PaginatedListResponse",
+    # Filter models
+    "FilterOperator",
+    "FilterOption",
+    "FilterQuery",
+    "FilterBuilder",
+    # Sort models
+    "SortOption",
+    # Pagination utilities
+    "parse_pagination_params",
+    "create_meta_object",
+    "apply_pagination_to_array",
+    "create_paginated_list_response",
+    # Filter utilities
+    "parse_filter_params",
+    "build_query_string",
+    "apply_filters",
+    # Sort utilities
+    "parse_sort_params",
+    "build_sort_string",
+    # Error utilities
+    "transform_error_to_snake_case",
+    "handle_api_error_snake_case",
+    # Services
     "AuthService",
     "RoleService",
     "PermissionService",

miso_client/models/error_response.py

@@ -33,9 +33,18 @@ class ErrorResponse(BaseModel):
 
     errors: List[str] = Field(..., description="List of error messages")
     type: str = Field(..., description="Error type URI (e.g., '/Errors/Bad Input')")
-    title: str = Field(..., description="Human-readable error title")
+    title: Optional[str] = Field(default=None, description="Human-readable error title")
     statusCode: int = Field(..., alias="status_code", description="HTTP status code")
     instance: Optional[str] = Field(default=None, description="Request instance URI")
+    request_key: Optional[str] = Field(
+        default=None, alias="requestKey", description="Request key for error tracking"
+    )
 
     class Config:
         populate_by_name = True  # Allow both camelCase and snake_case
+
+    # Support snake_case attribute access
+    @property
+    def status_code(self) -> int:
+        """Get statusCode as status_code (snake_case)."""
+        return self.statusCode

miso_client/models/filter.py

@@ -0,0 +1,140 @@
+"""
+Filter types for MisoClient SDK.
+
+This module contains Pydantic models and classes that define filter structures
+for query filtering matching the Miso/Dataplane API conventions.
+"""
+
+from typing import Any, List, Literal, Optional, Union
+
+from pydantic import BaseModel, Field
+
+FilterOperator = Literal[
+    "eq",
+    "neq",
+    "in",
+    "nin",
+    "gt",
+    "lt",
+    "gte",
+    "lte",
+    "contains",
+    "like",
+]
+
+
+class FilterOption(BaseModel):
+    """
+    Single filter option with field, operator, and value.
+
+    Fields:
+        field: Field name to filter on
+        op: Filter operator (eq, neq, in, nin, gt, lt, gte, lte, contains, like)
+        value: Filter value (supports single values or arrays for 'in'/'nin' operators)
+    """
+
+    field: str = Field(..., description="Field name to filter on")
+    op: FilterOperator = Field(..., description="Filter operator")
+    value: Union[str, int, float, bool, List[Any]] = Field(
+        ..., description="Filter value (supports arrays for 'in'/'nin' operators)"
+    )
+
+
+class FilterQuery(BaseModel):
+    """
+    Complete filter query with filters, sort, pagination, and field selection.
+
+    Fields:
+        filters: Optional list of filter options
+        sort: Optional list of sort options (field strings with optional '-' prefix for desc)
+        page: Optional page number (1-based)
+        page_size: Optional number of items per page
+        fields: Optional list of fields to include in response
+    """
+
+    filters: Optional[List[FilterOption]] = Field(
+        default=None, description="List of filter options"
+    )
+    sort: Optional[List[str]] = Field(
+        default=None,
+        description="List of sort options (e.g., ['-updated_at', 'created_at'])",
+    )
+    page: Optional[int] = Field(default=None, description="Page number (1-based)")
+    page_size: Optional[int] = Field(default=None, description="Number of items per page")
+    fields: Optional[List[str]] = Field(
+        default=None, description="List of fields to include in response"
+    )
+
+
+class FilterBuilder:
+    """
+    Builder pattern for dynamic filter construction.
+
+    Allows chaining filter additions for building complex filter queries.
+    """
+
+    def __init__(self):
+        """Initialize empty filter builder."""
+        self._filters: List[FilterOption] = []
+
+    def add(self, field: str, op: FilterOperator, value: Any) -> "FilterBuilder":
+        """
+        Add a filter option to the builder.
+
+        Args:
+            field: Field name to filter on
+            op: Filter operator
+            value: Filter value
+
+        Returns:
+            FilterBuilder instance for method chaining
+        """
+        self._filters.append(FilterOption(field=field, op=op, value=value))
+        return self
+
+    def add_many(self, filters: List[FilterOption]) -> "FilterBuilder":
+        """
+        Add multiple filter options to the builder.
+
+        Args:
+            filters: List of FilterOption objects
+
+        Returns:
+            FilterBuilder instance for method chaining
+        """
+        self._filters.extend(filters)
+        return self
+
+    def build(self) -> List[FilterOption]:
+        """
+        Build the filter list.
+
+        Returns:
+            List of FilterOption objects
+        """
+        return self._filters.copy()
+
+    def to_query_string(self) -> str:
+        """
+        Convert filters to query string format.
+
+        Format: ?filter=field:op:value&filter=field:op:value
+
+        Returns:
+            Query string with filter parameters
+        """
+        if not self._filters:
+            return ""
+
+        query_parts: List[str] = []
+        for filter_option in self._filters:
+            # Format value for query string
+            if isinstance(filter_option.value, list):
+                # For arrays (in/nin), join with commas
+                value_str = ",".join(str(v) for v in filter_option.value)
+            else:
+                value_str = str(filter_option.value)
+
+            query_parts.append(f"filter={filter_option.field}:{filter_option.op}:{value_str}")
+
+        return "&".join(query_parts)

miso_client/models/pagination.py

@@ -0,0 +1,66 @@
+"""
+Pagination types for MisoClient SDK.
+
+This module contains Pydantic models that define pagination structures
+for paginated list responses matching the Miso/Dataplane API conventions.
+"""
+
+from typing import Generic, List, TypeVar
+
+from pydantic import BaseModel, Field
+
+T = TypeVar("T")
+
+
+class Meta(BaseModel):
+    """
+    Pagination metadata for list responses.
+
+    Fields:
+        total_items: Total number of items across all pages
+        current_page: Current page number (1-based, maps from `page` query param)
+        page_size: Number of items per page (maps from `page_size` query param)
+        type: Resource type identifier (e.g., 'item', 'user', 'group')
+    """
+
+    total_items: int = Field(..., alias="totalItems", description="Total number of items")
+    current_page: int = Field(..., alias="currentPage", description="Current page number (1-based)")
+    page_size: int = Field(..., alias="pageSize", description="Number of items per page")
+    type: str = Field(..., description="Resource type identifier")
+
+    class Config:
+        populate_by_name = True  # Allow both snake_case and camelCase
+
+    # Support camelCase attribute access
+    @property
+    def totalItems(self) -> int:
+        """Get total_items as totalItems (camelCase)."""
+        return self.total_items
+
+    @property
+    def currentPage(self) -> int:
+        """Get current_page as currentPage (camelCase)."""
+        return self.current_page
+
+    @property
+    def pageSize(self) -> int:
+        """Get page_size as pageSize (camelCase)."""
+        return self.page_size
+
+
+class PaginatedListResponse(BaseModel, Generic[T]):
+    """
+    Paginated list response structure.
+
+    Generic type parameter T represents the item type in the data array.
+
+    Fields:
+        meta: Pagination metadata
+        data: Array of items for current page
+    """
+
+    meta: Meta = Field(..., description="Pagination metadata")
+    data: List[T] = Field(..., description="Array of items for current page")
+
+    class Config:
+        populate_by_name = True  # Allow both snake_case and camelCase

miso_client/models/sort.py

@@ -0,0 +1,25 @@
+"""
+Sort types for MisoClient SDK.
+
+This module contains Pydantic models that define sort structures
+for query sorting matching the Miso/Dataplane API conventions.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+SortOrder = Literal["asc", "desc"]
+
+
+class SortOption(BaseModel):
+    """
+    Sort option with field and order.
+
+    Fields:
+        field: Field name to sort by
+        order: Sort order ('asc' for ascending, 'desc' for descending)
+    """
+
+    field: str = Field(..., description="Field name to sort by")
+    order: SortOrder = Field(..., description="Sort order ('asc' or 'desc')")

miso_client/utils/error_utils.py

@@ -0,0 +1,104 @@
+"""
+Error utilities for MisoClient SDK.
+
+This module provides error transformation utilities for handling
+snake_case error responses from the API.
+"""
+
+from typing import Optional
+
+from ..errors import MisoClientError
+from ..models.error_response import ErrorResponse
+
+
+def transform_error_to_snake_case(error_data: dict) -> ErrorResponse:
+    """
+    Transform errors to snake_case format.
+
+    Converts error data dictionary to ErrorResponse object,
+    supporting both camelCase and snake_case field names.
+
+    Args:
+        error_data: Dictionary with error data (can be camelCase or snake_case)
+
+    Returns:
+        ErrorResponse object with standardized format
+
+    Examples:
+        >>> error_data = {
+        ...     'errors': ['Error message'],
+        ...     'type': '/Errors/Bad Input',
+        ...     'title': 'Bad Request',
+        ...     'status_code': 400,
+        ...     'instance': '/api/endpoint'
+        ... }
+        >>> error_response = transform_error_to_snake_case(error_data)
+        >>> error_response.statusCode
+        400
+    """
+    # ErrorResponse already supports both formats via populate_by_name=True
+    return ErrorResponse(**error_data)
+
+
+def handle_api_error_snake_case(
+    response_data: dict, status_code: int, instance: Optional[str] = None
+) -> MisoClientError:
+    """
+    Handle errors with snake_case response format.
+
+    Creates MisoClientError with ErrorResponse from snake_case API response.
+
+    Args:
+        response_data: Error response data from API (can be camelCase or snake_case)
+        status_code: HTTP status code (overrides status_code in response_data)
+        instance: Optional request instance URI (overrides instance in response_data)
+
+    Returns:
+        MisoClientError with structured ErrorResponse
+
+    Examples:
+        >>> response_data = {
+        ...     'errors': ['Validation failed'],
+        ...     'type': '/Errors/Validation',
+        ...     'title': 'Validation Error',
+        ...     'status_code': 422
+        ... }
+        >>> error = handle_api_error_snake_case(response_data, 422, '/api/endpoint')
+        >>> error.error_response.statusCode
+        422
+    """
+    # Create a copy to avoid mutating the original
+    data = response_data.copy()
+
+    # Override instance if provided
+    if instance:
+        data["instance"] = instance
+
+    # Override status_code if provided
+    data["status_code"] = status_code
+    # Also set camelCase version for consistency
+    data["statusCode"] = status_code
+
+    # Ensure title has a default if missing
+    if "title" not in data:
+        data["title"] = None
+
+    # Transform to ErrorResponse
+    error_response = transform_error_to_snake_case(data)
+
+    # Create error message from errors list
+    if error_response.errors:
+        if len(error_response.errors) == 1:
+            message = error_response.errors[0]
+        else:
+            title_prefix = f"{error_response.title}: " if error_response.title else ""
+            message = f"{title_prefix}{'; '.join(error_response.errors)}"
+    else:
+        message = error_response.title or "API Error"
+
+    # Create MisoClientError with ErrorResponse
+    return MisoClientError(
+        message=message,
+        status_code=status_code,
+        error_response=error_response,
+    )

miso_client/utils/filter.py

@@ -0,0 +1,256 @@
+"""
+Filter utilities for MisoClient SDK.
+
+This module provides reusable filter utilities for parsing filter parameters,
+building query strings, and applying filters to arrays.
+"""
+
+from typing import Any, Dict, List
+from urllib.parse import quote, unquote
+
+from ..models.filter import FilterOption, FilterQuery
+
+
+def parse_filter_params(params: dict) -> List[FilterOption]:
+    """
+    Parse filter query parameters into FilterOption list.
+
+    Parses `?filter=field:op:value` format into FilterOption objects.
+    Supports multiple filter parameters (array of filter strings).
+
+    Args:
+        params: Dictionary with query parameters (e.g., {'filter': ['status:eq:active', 'region:in:eu,us']})
+
+    Returns:
+        List of FilterOption objects
+
+    Examples:
+        >>> parse_filter_params({'filter': ['status:eq:active']})
+        [FilterOption(field='status', op='eq', value='active')]
+        >>> parse_filter_params({'filter': ['region:in:eu,us']})
+        [FilterOption(field='region', op='in', value=['eu', 'us'])]
+    """
+    filters: List[FilterOption] = []
+
+    # Get filter parameter (can be string or list)
+    filter_param = params.get("filter") or params.get("filters")
+    if not filter_param:
+        return filters
+
+    # Normalize to list
+    if isinstance(filter_param, str):
+        filter_strings = [filter_param]
+    elif isinstance(filter_param, list):
+        filter_strings = filter_param
+    else:
+        return filters
+
+    # Parse each filter string
+    for filter_str in filter_strings:
+        if not isinstance(filter_str, str):
+            continue
+
+        # Split by colon (field:op:value)
+        parts = filter_str.split(":", 2)
+        if len(parts) != 3:
+            continue  # Skip invalid filter format
+
+        field = unquote(parts[0].strip())
+        op = parts[1].strip()
+        value_str = unquote(parts[2].strip())
+
+        # Validate operator
+        valid_operators = ["eq", "neq", "in", "nin", "gt", "lt", "gte", "lte", "contains", "like"]
+        if op not in valid_operators:
+            continue  # Skip invalid operator
+
+        # Parse value based on operator
+        if op in ("in", "nin"):
+            # Array values: comma-separated
+            value = [v.strip() for v in value_str.split(",") if v.strip()]
+        else:
+            # Single value: try to parse as number/boolean, fallback to string
+            value = value_str
+            # Try to parse as integer
+            try:
+                if "." not in value_str:
+                    value = int(value_str)
+                else:
+                    value = float(value_str)
+            except (ValueError, TypeError):
+                # Try boolean
+                if value_str.lower() in ("true", "false"):
+                    value = value_str.lower() == "true"
+                else:
+                    value = value_str
+
+        filters.append(FilterOption(field=field, op=op, value=value))
+
+    return filters
+
+
+def build_query_string(filter_query: FilterQuery) -> str:
+    """
+    Convert FilterQuery object to query string.
+
+    Builds query string with filter, sort, page, page_size, and fields parameters.
+
+    Args:
+        filter_query: FilterQuery object with filters, sort, pagination, and fields
+
+    Returns:
+        Query string (e.g., '?filter=status:eq:active&page=1&page_size=25&sort=-updated_at')
+
+    Examples:
+        >>> from miso_client.models.filter import FilterQuery, FilterOption
+        >>> query = FilterQuery(
+        ...     filters=[FilterOption(field='status', op='eq', value='active')],
+        ...     page=1,
+        ...     page_size=25
+        ... )
+        >>> build_query_string(query)
+        'filter=status:eq:active&page=1&page_size=25'
+    """
+    query_parts: List[str] = []
+
+    # Add filters
+    if filter_query.filters:
+        for filter_option in filter_query.filters:
+            # Format value for query string
+            if isinstance(filter_option.value, list):
+                # For arrays (in/nin), join with commas (don't encode the comma delimiter)
+                # URL encode each value individually, then join with comma
+                value_parts = [quote(str(v)) for v in filter_option.value]
+                value_str = ",".join(value_parts)
+            else:
+                value_str = quote(str(filter_option.value))
+
+            # URL encode field
+            field_encoded = quote(filter_option.field)
+
+            query_parts.append(f"filter={field_encoded}:{filter_option.op}:{value_str}")
+
+    # Add sort
+    if filter_query.sort:
+        for sort_field in filter_query.sort:
+            query_parts.append(f"sort={quote(sort_field)}")
+
+    # Add pagination
+    if filter_query.page is not None:
+        query_parts.append(f"page={filter_query.page}")
+
+    if filter_query.page_size is not None:
+        query_parts.append(f"page_size={filter_query.page_size}")
+
+    # Add fields
+    if filter_query.fields:
+        fields_str = ",".join(quote(f) for f in filter_query.fields)
+        query_parts.append(f"fields={fields_str}")
+
+    return "&".join(query_parts)
+
+
+def apply_filters(items: List[Dict[str, Any]], filters: List[FilterOption]) -> List[Dict[str, Any]]:
+    """
+    Apply filters to array locally (for testing/mocks).
+
+    Args:
+        items: Array of dictionaries to filter
+        filters: List of FilterOption objects to apply
+
+    Returns:
+        Filtered array of items
+
+    Examples:
+        >>> items = [{'status': 'active', 'region': 'eu'}, {'status': 'inactive', 'region': 'us'}]
+        >>> filters = [FilterOption(field='status', op='eq', value='active')]
+        >>> apply_filters(items, filters)
+        [{'status': 'active', 'region': 'eu'}]
+    """
+    if not filters:
+        return items
+
+    filtered_items = items.copy()
+
+    for filter_option in filters:
+        field = filter_option.field
+        op = filter_option.op
+        value = filter_option.value
+
+        # Apply filter based on operator
+        if op == "eq":
+            filtered_items = [
+                item for item in filtered_items if field in item and item[field] == value
+            ]
+        elif op == "neq":
+            filtered_items = [
+                item for item in filtered_items if field not in item or item[field] != value
+            ]
+        elif op == "in":
+            if isinstance(value, list):
+                filtered_items = [
+                    item for item in filtered_items if field in item and item[field] in value
+                ]
+            else:
+                filtered_items = [
+                    item for item in filtered_items if field in item and item[field] == value
+                ]
+        elif op == "nin":
+            if isinstance(value, list):
+                filtered_items = [
+                    item for item in filtered_items if field not in item or item[field] not in value
+                ]
+            else:
+                filtered_items = [
+                    item for item in filtered_items if field not in item or item[field] != value
+                ]
+        elif op == "gt":
+            filtered_items = [
+                item
+                for item in filtered_items
+                if field in item and isinstance(item[field], (int, float)) and item[field] > value
+            ]
+        elif op == "lt":
+            filtered_items = [
+                item
+                for item in filtered_items
+                if field in item and isinstance(item[field], (int, float)) and item[field] < value
+            ]
+        elif op == "gte":
+            filtered_items = [
+                item
+                for item in filtered_items
+                if field in item and isinstance(item[field], (int, float)) and item[field] >= value
+            ]
+        elif op == "lte":
+            filtered_items = [
+                item
+                for item in filtered_items
+                if field in item and isinstance(item[field], (int, float)) and item[field] <= value
+            ]
+        elif op == "contains":
+            if isinstance(value, str):
+                filtered_items = [
+                    item
+                    for item in filtered_items
+                    if field in item and isinstance(item[field], str) and value in item[field]
+                ]
+            else:
+                # For non-string values, check if value is in list/array field
+                filtered_items = [
+                    item
+                    for item in filtered_items
+                    if field in item and isinstance(item[field], list) and value in item[field]
+                ]
+        elif op == "like":
+            if isinstance(value, str):
+                # Simple like matching (contains)
+                filtered_items = [
+                    item
+                    for item in filtered_items
+                    if field in item
+                    and isinstance(item[field], str)
+                    and value.lower() in item[field].lower()
+                ]
+
+    return filtered_items

miso_client/utils/http_client.py

@@ -583,3 +583,110 @@ class HttpClient:
         kwargs["headers"] = headers
 
         return await self.request(method, url, data, **kwargs)
+
+    async def get_with_filters(
+        self,
+        url: str,
+        filter_builder: Optional[Any] = None,
+        **kwargs,
+    ) -> Any:
+        """
+        Make GET request with filter builder support.
+
+        Args:
+            url: Request URL
+            filter_builder: Optional FilterBuilder instance with filters
+            **kwargs: Additional httpx request parameters
+
+        Returns:
+            Response data (JSON parsed)
+
+        Raises:
+            MisoClientError: If request fails
+
+        Examples:
+            >>> from miso_client.models.filter import FilterBuilder
+            >>> filter_builder = FilterBuilder().add('status', 'eq', 'active')
+            >>> response = await client.http_client.get_with_filters('/api/items', filter_builder)
+        """
+        from ..models.filter import FilterQuery
+        from ..utils.filter import build_query_string
+
+        # Build query string from filter builder
+        if filter_builder:
+            # Create FilterQuery from FilterBuilder
+            filter_query = FilterQuery(filters=filter_builder.build())
+            query_string = build_query_string(filter_query)
+
+            # Parse query string into params
+            if query_string:
+                from urllib.parse import parse_qs
+
+                # Parse query string into dict
+                query_params = parse_qs(query_string)
+                # Convert single-item lists to values
+                params = {k: v[0] if len(v) == 1 else v for k, v in query_params.items()}
+
+                # Merge with existing params
+                existing_params = kwargs.get("params", {})
+                if existing_params:
+                    # Merge params (filter builder takes precedence)
+                    merged_params = {**existing_params, **params}
+                else:
+                    merged_params = params
+
+                kwargs["params"] = merged_params
+
+        return await self.get(url, **kwargs)
+
+    async def get_paginated(
+        self,
+        url: str,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        **kwargs,
+    ) -> Any:
+        """
+        Make GET request with pagination support.
+
+        Args:
+            url: Request URL
+            page: Optional page number (1-based)
+            page_size: Optional number of items per page
+            **kwargs: Additional httpx request parameters
+
+        Returns:
+            PaginatedListResponse with meta and data (or raw response if format doesn't match)
+
+        Raises:
+            MisoClientError: If request fails
+
+        Examples:
+            >>> response = await client.http_client.get_paginated('/api/items', page=1, page_size=25)
+            >>> response.meta.total_items
+            120
+            >>> len(response.data)
+            25
+        """
+        from ..models.pagination import PaginatedListResponse
+
+        # Add pagination params
+        params = kwargs.get("params", {})
+        if page is not None:
+            params["page"] = page
+        if page_size is not None:
+            params["page_size"] = page_size
+
+        if params:
+            kwargs["params"] = params
+
+        # Make request
+        response_data = await self.get(url, **kwargs)
+
+        # Try to parse as PaginatedListResponse
+        try:
+            return PaginatedListResponse(**response_data)
+        except Exception:
+            # If response doesn't match PaginatedListResponse format, return as-is
+            # This allows flexibility for different response formats
+            return response_data

miso_client/utils/pagination.py

@@ -0,0 +1,157 @@
+"""
+Pagination utilities for MisoClient SDK.
+
+This module provides reusable pagination utilities for parsing pagination parameters,
+creating meta objects, and working with paginated responses.
+"""
+
+from typing import List, Tuple, TypeVar
+
+from ..models.pagination import Meta, PaginatedListResponse
+
+T = TypeVar("T")
+
+
+def parse_pagination_params(params: dict) -> Tuple[int, int]:
+    """
+    Parse query parameters to pagination values.
+
+    Parses `page` and `page_size` query parameters into `current_page` and `page_size`.
+    Both are 1-based (page starts at 1).
+
+    Args:
+        params: Dictionary with query parameters (e.g., {'page': '1', 'page_size': '25'})
+
+    Returns:
+        Tuple of (current_page, page_size) as integers
+
+    Examples:
+        >>> parse_pagination_params({'page': '1', 'page_size': '25'})
+        (1, 25)
+        >>> parse_pagination_params({'page': '2'})
+        (2, 25)  # Default page_size is 25
+    """
+    # Default values
+    default_page = 1
+    default_page_size = 25
+
+    # Parse page (must be >= 1)
+    page_str = params.get("page") or params.get("current_page")
+    if page_str is None:
+        current_page = default_page
+    else:
+        try:
+            current_page = int(page_str)
+            if current_page < 1:
+                current_page = default_page
+        except (ValueError, TypeError):
+            current_page = default_page
+
+    # Parse page_size (must be >= 1)
+    page_size_str = params.get("page_size") or params.get("pageSize")
+    if page_size_str is None:
+        page_size = default_page_size
+    else:
+        try:
+            page_size = int(page_size_str)
+            if page_size < 1:
+                page_size = default_page_size
+        except (ValueError, TypeError):
+            page_size = default_page_size
+
+    return (current_page, page_size)
+
+
+def create_meta_object(total_items: int, current_page: int, page_size: int, type: str) -> Meta:
+    """
+    Construct Meta object from pagination parameters.
+
+    Args:
+        total_items: Total number of items across all pages
+        current_page: Current page number (1-based)
+        page_size: Number of items per page
+        type: Resource type identifier (e.g., 'item', 'user', 'group')
+
+    Returns:
+        Meta object with pagination metadata
+
+    Examples:
+        >>> meta = create_meta_object(120, 1, 25, 'item')
+        >>> meta.total_items
+        120
+        >>> meta.current_page
+        1
+    """
+    return Meta(
+        total_items=total_items,
+        current_page=current_page,
+        page_size=page_size,
+        type=type,
+    )
+
+
+def apply_pagination_to_array(items: List[T], current_page: int, page_size: int) -> List[T]:
+    """
+    Apply pagination to array (for testing/mocks).
+
+    Args:
+        items: Array of items to paginate
+        current_page: Current page number (1-based)
+        page_size: Number of items per page
+
+    Returns:
+        Paginated subset of items for the specified page
+
+    Examples:
+        >>> items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+        >>> apply_pagination_to_array(items, 1, 3)
+        [1, 2, 3]
+        >>> apply_pagination_to_array(items, 2, 3)
+        [4, 5, 6]
+    """
+    if not items:
+        return []
+
+    if current_page < 1:
+        current_page = 1
+    if page_size < 1:
+        page_size = 25
+
+    # Calculate start and end indices
+    start_index = (current_page - 1) * page_size
+    end_index = start_index + page_size
+
+    # Return paginated subset
+    return items[start_index:end_index]
+
+
+def create_paginated_list_response(
+    items: List[T],
+    total_items: int,
+    current_page: int,
+    page_size: int,
+    type: str,
+) -> PaginatedListResponse[T]:
+    """
+    Wrap array + meta into standard paginated response.
+
+    Args:
+        items: Array of items for current page
+        total_items: Total number of items across all pages
+        current_page: Current page number (1-based)
+        page_size: Number of items per page
+        type: Resource type identifier (e.g., 'item', 'user', 'group')
+
+    Returns:
+        PaginatedListResponse with meta and data
+
+    Examples:
+        >>> items = [{'id': 1}, {'id': 2}]
+        >>> response = create_paginated_list_response(items, 10, 1, 2, 'item')
+        >>> response.meta.total_items
+        10
+        >>> len(response.data)
+        2
+    """
+    meta = create_meta_object(total_items, current_page, page_size, type)
+    return PaginatedListResponse(meta=meta, data=items)

miso_client/utils/sort.py

@@ -0,0 +1,116 @@
+"""
+Sort utilities for MisoClient SDK.
+
+This module provides reusable sort utilities for parsing sort parameters
+and building sort query strings.
+"""
+
+from typing import List
+from urllib.parse import quote
+
+from ..models.sort import SortOption
+
+
+def parse_sort_params(params: dict) -> List[SortOption]:
+    """
+    Parse sort query parameters into SortOption list.
+
+    Parses `?sort=-field` format into SortOption objects.
+    Supports multiple sort parameters (array of sort strings).
+    Prefix with '-' for descending order, otherwise ascending.
+
+    Args:
+        params: Dictionary with query parameters (e.g., {'sort': '-updated_at'} or {'sort': ['-updated_at', 'created_at']})
+
+    Returns:
+        List of SortOption objects
+
+    Examples:
+        >>> parse_sort_params({'sort': '-updated_at'})
+        [SortOption(field='updated_at', order='desc')]
+        >>> parse_sort_params({'sort': ['-updated_at', 'created_at']})
+        [SortOption(field='updated_at', order='desc'), SortOption(field='created_at', order='asc')]
+    """
+    sort_options: List[SortOption] = []
+
+    # Get sort parameter (can be string or list)
+    sort_param = params.get("sort")
+    if not sort_param:
+        return sort_options
+
+    # Normalize to list
+    if isinstance(sort_param, str):
+        sort_strings = [sort_param]
+    elif isinstance(sort_param, list):
+        sort_strings = sort_param
+    else:
+        return sort_options
+
+    # Parse each sort string
+    for sort_str in sort_strings:
+        if not isinstance(sort_str, str):
+            continue
+
+        sort_str = sort_str.strip()
+        if not sort_str:
+            continue
+
+        # Check for descending order (prefix with '-')
+        if sort_str.startswith("-"):
+            field = sort_str[1:].strip()
+            order = "desc"
+        else:
+            field = sort_str.strip()
+            order = "asc"
+
+        if field:
+            sort_options.append(SortOption(field=field, order=order))
+
+    return sort_options
+
+
+def build_sort_string(sort_options: List[SortOption]) -> str:
+    """
+    Convert SortOption list to query string format.
+
+    Converts SortOption objects to sort query string format.
+    Descending order fields are prefixed with '-'.
+
+    Args:
+        sort_options: List of SortOption objects
+
+    Returns:
+        Sort query string (e.g., '-updated_at,created_at' or single value '-updated_at')
+
+    Examples:
+        >>> from miso_client.models.sort import SortOption
+        >>> sort_options = [SortOption(field='updated_at', order='desc')]
+        >>> build_sort_string(sort_options)
+        '-updated_at'
+        >>> sort_options = [
+        ...     SortOption(field='updated_at', order='desc'),
+        ...     SortOption(field='created_at', order='asc')
+        ... ]
+        >>> build_sort_string(sort_options)
+        '-updated_at,created_at'
+    """
+    if not sort_options:
+        return ""
+
+    sort_strings: List[str] = []
+    for sort_option in sort_options:
+        field = sort_option.field
+        order = sort_option.order
+
+        # URL encode field name
+        field_encoded = quote(field)
+
+        # Add '-' prefix for descending order
+        if order == "desc":
+            sort_strings.append(f"-{field_encoded}")
+        else:
+            sort_strings.append(field_encoded)
+
+    # Join multiple sorts with comma (if needed for single sort param)
+    # Or return as comma-separated string
+    return ",".join(sort_strings)

{miso_client-0.4.0.dist-info → miso_client-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: miso-client
-Version: 0.4.0
+Version: 0.5.0
 Summary: Python client SDK for AI Fabrix authentication, authorization, and logging
 Home-page: https://github.com/aifabrix/miso-client-python
 Author: AI Fabrix Team
@@ -611,6 +611,225 @@ print(error_response.statusCode)  # 422
 print(error_response.instance)   # "/api/endpoint"
 ```
 
+---
+
+### Pagination, Filtering, and Sorting Utilities
+
+**What happens:** The SDK provides reusable utilities for pagination, filtering, sorting, and error handling that work with any API endpoint.
+
+#### Pagination
+
+**Pagination Parameters:**
+- `page`: Page number (1-based, defaults to 1)
+- `page_size`: Number of items per page (defaults to 25)
+
+```python
+from miso_client import (
+    parse_pagination_params,
+    create_paginated_list_response,
+    PaginatedListResponse,
+)
+
+# Parse pagination from query parameters
+params = {"page": "1", "page_size": "25"}
+current_page, page_size = parse_pagination_params(params)
+
+# Create paginated response
+items = [{"id": 1}, {"id": 2}]
+response = create_paginated_list_response(
+    items,
+    total_items=120,
+    current_page=1,
+    page_size=25,
+    type="item"
+)
+
+# Response structure:
+# {
+#   "meta": {
+#     "total_items": 120,
+#     "current_page": 1,
+#     "page_size": 25,
+#     "type": "item"
+#   },
+#   "data": [{"id": 1}, {"id": 2}]
+# }
+```
+
+#### Filtering
+
+**Filter Operators:** `eq`, `neq`, `in`, `nin`, `gt`, `lt`, `gte`, `lte`, `contains`, `like`
+
+**Filter Format:** `field:op:value` (e.g., `status:eq:active`)
+
+```python
+from miso_client import FilterBuilder, parse_filter_params, build_query_string
+
+# Dynamic filter building with FilterBuilder
+filter_builder = FilterBuilder() \
+    .add('status', 'eq', 'active') \
+    .add('region', 'in', ['eu', 'us']) \
+    .add('created_at', 'gte', '2024-01-01')
+
+# Get query string
+query_string = filter_builder.to_query_string()
+# Returns: "filter=status:eq:active&filter=region:in:eu,us&filter=created_at:gte:2024-01-01"
+
+# Parse existing filter parameters
+params = {'filter': ['status:eq:active', 'region:in:eu,us']}
+filters = parse_filter_params(params)
+# Returns: [FilterOption(field='status', op='eq', value='active'), ...]
+
+# Use with HTTP client
+response = await client.http_client.get_with_filters(
+    '/api/items',
+    filter_builder=filter_builder
+)
+```
+
+**Building Complete Filter Queries:**
+
+```python
+from miso_client import FilterQuery, FilterOption, build_query_string
+
+# Create filter query with filters, sort, pagination, and fields
+filter_query = FilterQuery(
+    filters=[
+        FilterOption(field='status', op='eq', value='active'),
+        FilterOption(field='region', op='in', value=['eu', 'us'])
+    ],
+    sort=['-updated_at', 'created_at'],
+    page=1,
+    page_size=25,
+    fields=['id', 'name', 'status']
+)
+
+# Build query string
+query_string = build_query_string(filter_query)
+```
+
+#### Sorting
+
+**Sort Format:** `-field` for descending, `field` for ascending (e.g., `-updated_at`, `created_at`)
+
+```python
+from miso_client import parse_sort_params, build_sort_string, SortOption
+
+# Parse sort parameters
+params = {'sort': '-updated_at'}
+sort_options = parse_sort_params(params)
+# Returns: [SortOption(field='updated_at', order='desc')]
+
+# Parse multiple sorts
+params = {'sort': ['-updated_at', 'created_at']}
+sort_options = parse_sort_params(params)
+# Returns: [
+#   SortOption(field='updated_at', order='desc'),
+#   SortOption(field='created_at', order='asc')
+# ]
+
+# Build sort string
+sort_options = [
+    SortOption(field='updated_at', order='desc'),
+    SortOption(field='created_at', order='asc')
+]
+sort_string = build_sort_string(sort_options)
+# Returns: "-updated_at,created_at"
+```
+
+#### Combined Usage
+
+**Pagination + Filter + Sort:**
+
+```python
+from miso_client import (
+    FilterBuilder,
+    FilterQuery,
+    build_query_string,
+    parse_pagination_params,
+)
+
+# Build filters
+filter_builder = FilterBuilder() \
+    .add('status', 'eq', 'active') \
+    .add('region', 'in', ['eu', 'us'])
+
+# Parse pagination
+params = {'page': '1', 'page_size': '25'}
+current_page, page_size = parse_pagination_params(params)
+
+# Create complete query
+filter_query = FilterQuery(
+    filters=filter_builder.build(),
+    sort=['-updated_at'],
+    page=current_page,
+    page_size=page_size
+)
+
+# Build query string
+query_string = build_query_string(filter_query)
+
+# Use with HTTP client
+response = await client.http_client.get_with_filters(
+    '/api/items',
+    filter_builder=filter_builder,
+    params={'page': current_page, 'page_size': page_size}
+)
+```
+
+**Or use pagination helper:**
+
+```python
+# Get paginated response
+response = await client.http_client.get_paginated(
+    '/api/items',
+    page=1,
+    page_size=25
+)
+
+# Response is automatically parsed as PaginatedListResponse
+print(response.meta.total_items)  # 120
+print(response.meta.current_page)  # 1
+print(len(response.data))  # 25
+```
+
+#### Metadata Filter Integration
+
+**Working with `/metadata/filter` endpoint:**
+
+```python
+# Get metadata filters from endpoint
+metadata_response = await client.http_client.post(
+    "/api/v1/metadata/filter",
+    {"documentStorageKey": "my-doc-storage"}
+)
+
+# Convert AccessFieldFilter to FilterBuilder
+filter_builder = FilterBuilder()
+for access_filter in metadata_response.mandatoryFilters:
+    filter_builder.add(access_filter.field, 'in', access_filter.values)
+
+# Use with query utilities
+query_string = filter_builder.to_query_string()
+
+# Apply to API requests
+response = await client.http_client.get_with_filters(
+    '/api/items',
+    filter_builder=filter_builder
+)
+```
+
+**Features:**
+
+- **Snake_case Convention**: All utilities use snake_case to match Miso/Dataplane API
+- **Type Safety**: Full type hints with Pydantic models
+- **Dynamic Filtering**: FilterBuilder supports method chaining for complex filters
+- **Local Testing**: `apply_filters()` and `apply_pagination_to_array()` for local filtering/pagination in tests
+- **URL Encoding**: Automatic URL encoding for field names and values
+- **Backward Compatible**: Works alongside existing HTTP client methods
+
+---
+
 ### Common Tasks
 
 **Add authentication middleware (FastAPI):**

{miso_client-0.4.0.dist-info → miso_client-0.5.0.dist-info}/RECORD

@@ -1,9 +1,12 @@
-miso_client/__init__.py,sha256=MjiF-VJCkY6_s5_Oy8U43ZRa-XRVgrTpco-PnGPBTC4,14395
+miso_client/__init__.py,sha256=iDpRsYBbBDrLQFNJdtDlv4yrg1pvwNZpD2C3TYAyOSo,15595
 miso_client/errors.py,sha256=uyS5j-_bUCA5gbINPYQd0wMpGsaEH0tJRK0obQTq2oo,1976
 miso_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 miso_client/models/__init__.py,sha256=lMnzU7j2Z5_UehvOeIrbJIo3MH4j5KINGfU1vJTzTyU,139
 miso_client/models/config.py,sha256=TLckmwajrdnJpMTsjCtaFkz8wFAXcEQJfKjXQ8ww6vM,8024
-miso_client/models/error_response.py,sha256=Dd-Rm2ylxU9ssYUsGBifjT-Let2MMxn28LJszQCO5bY,1362
+miso_client/models/error_response.py,sha256=YBQkchdWOo6NjdNpLlOvGaIhOwA1MJzkTS2oeU0e2Mk,1694
+miso_client/models/filter.py,sha256=3XWVxAjtUP78KPocd4-Ko9SijeRXm3jWVVBCXDPnXuI,4111
+miso_client/models/pagination.py,sha256=f-YbspLrQH3ZhDYzbMCTloeKF2EyaSi7zjFLgh6dhBQ,2078
+miso_client/models/sort.py,sha256=CutVQnYC4uRgesJ8zgd4OmPGZIop1KzvtgiTjNproSM,621
 miso_client/services/__init__.py,sha256=2ok62Z9kaS0Zze-OxRkxEJ4JidzN9jL_pzGMOxpZppQ,489
 miso_client/services/auth.py,sha256=hYnHEoTNgeH_g0ItoVDq99fBZCZX0o-0o-9gRxqZYmw,5465
 miso_client/services/cache.py,sha256=lXcLcRm56snOX3AQiEKi-j7FIikCLYnEK2HXxBkxm2M,6510
@@ -15,12 +18,16 @@ miso_client/services/role.py,sha256=qmxhk54QUGCjCuCWm_ruDlTq7iT9yOicfUvdRVkFKUI,
 miso_client/utils/__init__.py,sha256=HArSxVKrmCqFkqFOPwe1i3B2IBHJ1vRqYu98c_KASV0,366
 miso_client/utils/config_loader.py,sha256=yZk4pXNIBu3i61KqxM8QwsjraM0xhqUcH2THl8-DMu0,3027
 miso_client/utils/data_masker.py,sha256=D7AEyViGxoShLa5UUZHYhRCPQMPKqX7qNilTK9h87OM,7035
-miso_client/utils/http_client.py,sha256=AwlP0h17SdJ2lqf5j19HVztjvvMrCPTybkbWdvGzM38,20252
+miso_client/utils/error_utils.py,sha256=B-BXmDTTj6II1HwjC_DE6o9QKOMs6B3bzFXkOiPhf20,3274
+miso_client/utils/filter.py,sha256=obkdQ3FFD69Qg0VviFMoM8y6zAP5JYBaIujmOT9diU8,8984
+miso_client/utils/http_client.py,sha256=H386RsKjiw-JG7XhrTn8gCRDMWMvp8s7bC1jqa7qvGk,23807
 miso_client/utils/internal_http_client.py,sha256=jgiaO94EiIUbMQWUKN4FhYqOQ9r0BZea0_grRcOepL4,16078
 miso_client/utils/jwt_tools.py,sha256=-pvz5nk5BztEnhFnL-dtOv8Q5E0G2oh4RwFrVk2rVpg,1981
+miso_client/utils/pagination.py,sha256=_sUzAGSCiUujVa9W3nedVRaCx18_9MuT_9bBlWmVc9o,4449
 miso_client/utils/sensitive_fields_loader.py,sha256=EHODxyM1Gw7hgKXCvJ1B4Hf4LZqcEqWEXu4q5CPFaic,3667
-miso_client-0.4.0.dist-info/licenses/LICENSE,sha256=3hoU8LdT9_EIFIx6FjMk5sQnVCBMX3FRIOzqqy5im4c,1076
-miso_client-0.4.0.dist-info/METADATA,sha256=Ek0HsqCnGba1PhmwPWre-KSrxVcOthJ1XtDBuObGyUw,22690
-miso_client-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-miso_client-0.4.0.dist-info/top_level.txt,sha256=8i_FNeRn8PRy6scnXOpVr-IJYsArkqIvxRMTZPtik9E,12
-miso_client-0.4.0.dist-info/RECORD,,
+miso_client/utils/sort.py,sha256=_bCLRCGevgNkXYqsgXasc3vaDQwkXV76kgHIyw-dato,3438
+miso_client-0.5.0.dist-info/licenses/LICENSE,sha256=3hoU8LdT9_EIFIx6FjMk5sQnVCBMX3FRIOzqqy5im4c,1076
+miso_client-0.5.0.dist-info/METADATA,sha256=ZzmZZNHxnv4n3P95ZJgMAPFKRE3gLTgYUhCG9sh20C4,28396
+miso_client-0.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+miso_client-0.5.0.dist-info/top_level.txt,sha256=8i_FNeRn8PRy6scnXOpVr-IJYsArkqIvxRMTZPtik9E,12
+miso_client-0.5.0.dist-info/RECORD,,