miso-client 0.4.0__tar.gz → 0.5.0__tar.gz

{miso_client-0.4.0 → miso_client-0.5.0}/CHANGELOG.md

@@ -5,6 +5,93 @@ All notable changes to the MisoClient SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2025-11-02
+
+### Added
+
+- **Pagination Utilities**: Complete pagination support for list responses
+  - `Meta` and `PaginatedListResponse` Pydantic models for standardized paginated responses
+  - `parse_pagination_params()` function to parse `page` and `page_size` query parameters
+  - `create_meta_object()` function to construct pagination metadata objects
+  - `apply_pagination_to_array()` function for local pagination in tests/mocks
+  - `create_paginated_list_response()` function to wrap data with pagination metadata
+  - Support for both snake_case (`total_items`, `current_page`, `page_size`) and camelCase (`totalItems`, `currentPage`, `pageSize`) attribute access
+  - Full type safety with Pydantic models and generic type support
+
+- **Filtering Utilities**: Comprehensive filtering support for API queries
+  - `FilterOption`, `FilterQuery`, and `FilterBuilder` classes for building filter queries
+  - `FilterOperator` type supporting: `eq`, `neq`, `in`, `nin`, `gt`, `lt`, `gte`, `lte`, `contains`, `like`
+  - `parse_filter_params()` function to parse `filter=field:op:value` query parameters
+  - `build_query_string()` function to convert `FilterQuery` objects to URL query strings
+  - `apply_filters()` function for local filtering in tests/mocks
+  - `FilterBuilder` class with fluent API for method chaining (e.g., `FilterBuilder().add('status', 'eq', 'active').add('region', 'in', ['eu', 'us'])`)
+  - URL encoding support for field names and values (comma separators preserved for array values)
+  - Integration with `/metadata/filter` endpoint through `FilterBuilder` compatibility with `AccessFieldFilter`
+
+- **Sorting Utilities**: Sort parameter parsing and building
+  - `SortOption` Pydantic model with `field` and `order` (asc/desc) properties
+  - `parse_sort_params()` function to parse `sort=-field` query parameters
+  - `build_sort_string()` function to convert `SortOption` lists to query string format
+  - Support for multiple sort fields with ascending/descending order
+  - URL encoding for field names with special characters
+
+- **Error Handling Utilities**: Enhanced error response transformation and handling
+  - `transform_error_to_snake_case()` function for converting error dictionaries to `ErrorResponse` objects
+  - `handle_api_error_snake_case()` function for creating `MisoClientError` from API error responses
+  - Support for both camelCase and snake_case field names in error responses
+  - Automatic parameter overriding (instance and status_code parameters override response data)
+  - Graceful handling of missing optional fields (title, instance, request_key)
+
+- **HTTP Client Enhancements**: New helper methods for filtered and paginated requests
+  - `get_with_filters()` method for making GET requests with `FilterBuilder` support
+  - `get_paginated()` method for making GET requests with pagination parameters
+  - Automatic query string building from filter/sort/pagination options
+  - Flexible response parsing (returns `PaginatedListResponse` when format matches, raw response otherwise)
+
+- **ErrorResponse Model Enhancements**:
+  - Added `request_key` field for error tracking (supports both `request_key` and `requestKey` aliases)
+  - Made `title` field optional (defaults to `None`) for graceful handling of missing titles
+  - Added `status_code` property getter for snake_case access (complements `statusCode` camelCase field)
+  - Full support for both snake_case and camelCase attribute access
+
+- **Model Exports**: All new models and utilities exported from main module
+  - Pagination: `Meta`, `PaginatedListResponse`, `parse_pagination_params`, `create_meta_object`, `apply_pagination_to_array`, `create_paginated_list_response`
+  - Filtering: `FilterOperator`, `FilterOption`, `FilterQuery`, `FilterBuilder`, `parse_filter_params`, `build_query_string`, `apply_filters`
+  - Sorting: `SortOption`, `parse_sort_params`, `build_sort_string`
+  - Error: `transform_error_to_snake_case`, `handle_api_error_snake_case`
+  - All utilities follow snake_case naming convention matching Miso/Dataplane API conventions
+
+### Changed
+
+- **ErrorResponse Model**: Made `title` field optional to support APIs that don't provide titles
+  - Old: `title: str = Field(..., description="Human-readable error title")`
+  - New: `title: Optional[str] = Field(default=None, description="Human-readable error title")`
+  - Backward compatible - existing code with required titles still works
+
+- **handle_api_error_snake_case Function**: Enhanced parameter override behavior
+  - `instance` parameter now overrides instance in response_data (was only set if missing)
+  - `status_code` parameter now always overrides status_code in response_data (was only set if missing)
+  - Better error message generation when title is missing
+
+### Technical Improvements
+
+- **Type Safety**: Full type hints throughout all new utilities and models
+- **Pydantic Models**: All new data structures use Pydantic for validation and serialization
+- **Property Getters**: Added property getters to support both snake_case and camelCase attribute access in models
+- **URL Encoding**: Smart encoding that preserves comma delimiters in array filter values
+- **Comprehensive Tests**: 123 unit tests covering all utilities with 100% coverage for models and utilities
+- **Documentation**: Complete README documentation with usage examples for all utilities
+- **Snake_case Convention**: All utilities follow Python snake_case naming to match Miso/Dataplane API conventions
+
+### Documentation
+
+- Added comprehensive README section for pagination, filtering, and sorting utilities
+- Usage examples for all utilities including combined usage patterns
+- Integration examples with `/metadata/filter` endpoint
+- Type hints and docstrings for all public APIs
+
+---
+
 ## [0.4.0] - 2025-11-02
 
 ### Added

{miso_client-0.4.0/miso_client.egg-info → miso_client-0.5.0}/PKG-INFO

@@ -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 → miso_client-0.5.0}/README.md

@@ -562,6 +562,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 → miso_client-0.5.0}/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-0.4.0 → miso_client-0.5.0}/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