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

miso_client/__init__.py

@@ -26,6 +26,10 @@ from .models.config import (
     RoleResult,
     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
@@ -34,9 +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.1.0"
+__version__ = "0.5.0"
 __author__ = "AI Fabrix Team"
 __license__ = "MIT"
 
@@ -60,14 +74,29 @@ class MisoClient:
             config: MisoClient configuration including controller URL, client credentials, etc.
         """
         self.config = config
-        self.http_client = HttpClient(config)
+
+        # Create InternalHttpClient first (pure HTTP functionality, no logging)
+        self._internal_http_client = InternalHttpClient(config)
+
+        # Create Redis service
         self.redis = RedisService(config.redis)
+
+        # Create LoggerService with InternalHttpClient (to avoid circular dependency)
+        # LoggerService uses InternalHttpClient for sending logs to prevent audit loops
+        self.logger = LoggerService(self._internal_http_client, self.redis)
+
+        # Create public HttpClient wrapping InternalHttpClient with logger
+        # This HttpClient adds automatic ISO 27001 compliant audit and debug logging
+        self.http_client = HttpClient(config, self.logger)
+
         # Cache service (uses Redis if available, falls back to in-memory)
         self.cache = CacheService(self.redis)
+
+        # Services use public HttpClient (with audit logging)
         self.auth = AuthService(self.http_client, self.redis)
         self.roles = RoleService(self.http_client, self.cache)
         self.permissions = PermissionService(self.http_client, self.cache)
-        self.logger = LoggerService(self.http_client, self.redis)
+
         # Encryption service (reads ENCRYPTION_KEY from environment by default)
         self.encryption = EncryptionService()
         self.initialized = False
@@ -473,6 +502,33 @@ __all__ = [
     "ClientTokenResponse",
     "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/errors.py

@@ -4,12 +4,21 @@ SDK exceptions and error handling.
 This module defines custom exceptions for the MisoClient SDK.
 """
 
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..models.error_response import ErrorResponse
+
 
 class MisoClientError(Exception):
     """Base exception for MisoClient SDK errors."""
 
     def __init__(
-        self, message: str, status_code: int | None = None, error_body: dict | None = None
+        self,
+        message: str,
+        status_code: int | None = None,
+        error_body: dict | None = None,
+        error_response: "ErrorResponse | None" = None,
     ):
         """
         Initialize MisoClient error.
@@ -18,11 +27,23 @@ class MisoClientError(Exception):
             message: Error message
             status_code: HTTP status code if applicable
             error_body: Sanitized error response body (secrets masked)
+            error_response: Structured error response object (RFC 7807-style)
         """
         super().__init__(message)
         self.message = message
         self.status_code = status_code
         self.error_body = error_body if error_body is not None else None
+        self.error_response = error_response
+
+        # Enhance message with structured error information if available
+        if error_response and error_response.errors:
+            if len(error_response.errors) == 1:
+                self.message = error_response.errors[0]
+            else:
+                self.message = f"{error_response.title}: {'; '.join(error_response.errors)}"
+            # Override status_code from structured response if available
+            if error_response.statusCode:
+                self.status_code = error_response.statusCode
 
 
 class AuthenticationError(MisoClientError):

miso_client/models/__init__.py

@@ -1 +1,5 @@
 """Pydantic models for MisoClient configuration and data types."""
+
+from .error_response import ErrorResponse
+
+__all__ = ["ErrorResponse"]

miso_client/models/error_response.py

@@ -0,0 +1,50 @@
+"""
+Structured error response model following RFC 7807-style format.
+
+This module provides a generic error response interface that can be used
+across different applications for consistent error handling.
+"""
+
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ErrorResponse(BaseModel):
+    """
+    Structured error response following RFC 7807-style format.
+
+    This model represents a standardized error response structure that includes:
+    - Multiple error messages
+    - Error type identifier
+    - Human-readable title
+    - HTTP status code
+    - Request instance URI (optional)
+
+    Example:
+        {
+            "errors": ["Error message 1", "Error message 2"],
+            "type": "/Errors/Bad Input",
+            "title": "Bad Request",
+            "statusCode": 400,
+            "instance": "/OpenApi/rest/Xzy"
+        }
+    """
+
+    errors: List[str] = Field(..., description="List of error messages")
+    type: str = Field(..., description="Error type URI (e.g., '/Errors/Bad Input')")
+    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/services/logger.py

@@ -14,23 +14,23 @@ from typing import Any, Dict, Literal, Optional
 from ..models.config import ClientLoggingOptions, LogEntry
 from ..services.redis import RedisService
 from ..utils.data_masker import DataMasker
-from ..utils.http_client import HttpClient
+from ..utils.internal_http_client import InternalHttpClient
 from ..utils.jwt_tools import decode_token
 
 
 class LoggerService:
     """Logger service for application logging and audit events."""
 
-    def __init__(self, http_client: HttpClient, redis: RedisService):
+    def __init__(self, internal_http_client: InternalHttpClient, redis: RedisService):
         """
         Initialize logger service.
 
         Args:
-            http_client: HTTP client instance
+            internal_http_client: Internal HTTP client instance (used for log sending)
             redis: Redis service instance
         """
-        self.config = http_client.config
-        self.http_client = http_client
+        self.config = internal_http_client.config
+        self.internal_http_client = internal_http_client
         self.redis = redis
         self.mask_sensitive_data = True  # Default: mask sensitive data
         self.correlation_counter = 0
@@ -357,12 +357,13 @@ class LoggerService:
                 return  # Successfully queued in Redis
 
         # Fallback to unified logging endpoint with client credentials
+        # Use InternalHttpClient to avoid circular dependency with HttpClient
         try:
             # Backend extracts environment and application from client credentials
             log_payload = log_entry.model_dump(
                 exclude={"environment", "application"}, exclude_none=True
             )
-            await self.http_client.request("POST", "/api/logs", log_payload)
+            await self.internal_http_client.request("POST", "/api/logs", log_payload)
         except Exception:
             # Failed to send log to controller
             # Silently fail to avoid infinite logging loops

miso_client/utils/data_masker.py

@@ -5,7 +5,9 @@ Implements ISO 27001 data protection controls by masking sensitive fields
 in log entries and context data.
 """
 
-from typing import Any, Set
+from typing import Any, Optional, Set
+
+from .sensitive_fields_loader import get_sensitive_fields_array
 
 
 class DataMasker:
@@ -13,8 +15,8 @@ class DataMasker:
 
     MASKED_VALUE = "***MASKED***"
 
-    # Set of sensitive field names (normalized)
-    _sensitive_fields: Set[str] = {
+    # Hardcoded set of sensitive field names (normalized) - fallback if JSON cannot be loaded
+    _hardcoded_sensitive_fields: Set[str] = {
         "password",
         "passwd",
         "pwd",
@@ -38,6 +40,73 @@ class DataMasker:
         "secretkey",
     }
 
+    # Cached merged sensitive fields (loaded on first use)
+    _sensitive_fields: Optional[Set[str]] = None
+    _config_loaded: bool = False
+
+    @classmethod
+    def _load_config(cls, config_path: Optional[str] = None) -> None:
+        """
+        Load sensitive fields configuration from JSON and merge with hardcoded defaults.
+
+        This method is called automatically on first use. It loads JSON configuration
+        and merges it with hardcoded defaults, ensuring backward compatibility.
+
+        Args:
+            config_path: Optional custom path to JSON config file
+        """
+        if cls._config_loaded:
+            return
+
+        # Start with hardcoded fields as base
+        merged_fields = set(cls._hardcoded_sensitive_fields)
+
+        try:
+            # Try to load fields from JSON configuration
+            json_fields = get_sensitive_fields_array(config_path)
+            if json_fields:
+                # Normalize and add JSON fields (same normalization as hardcoded fields)
+                for field in json_fields:
+                    if isinstance(field, str):
+                        # Normalize: lowercase and remove underscores/hyphens
+                        normalized = field.lower().replace("_", "").replace("-", "")
+                        merged_fields.add(normalized)
+        except Exception:
+            # If JSON loading fails, fall back to hardcoded fields only
+            pass
+
+        cls._sensitive_fields = merged_fields
+        cls._config_loaded = True
+
+    @classmethod
+    def _get_sensitive_fields(cls) -> Set[str]:
+        """
+        Get the set of sensitive fields (loads config on first call).
+
+        Returns:
+            Set of normalized sensitive field names
+        """
+        if not cls._config_loaded:
+            cls._load_config()
+        assert cls._sensitive_fields is not None
+        return cls._sensitive_fields
+
+    @classmethod
+    def set_config_path(cls, config_path: str) -> None:
+        """
+        Set custom path for sensitive fields configuration.
+
+        Must be called before first use of DataMasker methods if custom path is needed.
+        Otherwise, default path or environment variable will be used.
+
+        Args:
+            config_path: Path to JSON configuration file
+        """
+        # Reset cache to force reload with new path
+        cls._config_loaded = False
+        cls._sensitive_fields = None
+        cls._load_config(config_path)
+
     @classmethod
     def is_sensitive_field(cls, key: str) -> bool:
         """
@@ -52,12 +121,15 @@ class DataMasker:
         # Normalize key: lowercase and remove underscores/hyphens
         normalized_key = key.lower().replace("_", "").replace("-", "")
 
+        # Get sensitive fields (loads config on first use)
+        sensitive_fields = cls._get_sensitive_fields()
+
         # Check exact match
-        if normalized_key in cls._sensitive_fields:
+        if normalized_key in sensitive_fields:
             return True
 
         # Check if field contains sensitive keywords
-        for sensitive_field in cls._sensitive_fields:
+        for sensitive_field in sensitive_fields:
             if sensitive_field in normalized_key:
                 return True