globkurier-api-mcp 0.2.0__tar.gz

globkurier_api_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: globkurier-api-mcp
+Version: 0.2.0
+Summary: MCP server for GlobKurier API - Hexagonal Architecture with CQRS
+Author-email: GlobKurier <it@globkurier.pl>
+License: MIT
+Project-URL: Homepage, https://github.com/GlobKurier-pl/mcp-server
+Project-URL: Repository, https://github.com/GlobKurier-pl/mcp-server
+Project-URL: Documentation, https://github.com/GlobKurier-pl/mcp-server#readme
+Keywords: mcp,shipping,logistics,globkurier,dpd,inpost,courier
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+
+<!-- mcp-name: io.github.globkurier-pl/mcp-server -->
+
+# GlobKurier MCP Server
+
+> [Polska wersja dokumentacji](./README.pl.md)
+
+[Model Context Protocol](https://modelcontextprotocol.io/) server for the [GlobKurier](https://www.globkurier.pl) API. Enables AI assistants (Claude, Cursor, Cline and others) to track shipments, search shipping products and generate purchase links.
+
+## Installation
+
+### Recommended: Hosted server (no local installation)
+
+```json
+{
+  "mcpServers": {
+    "globkurier": {
+      "type": "http",
+      "url": "https://mcp.globkurier.pl/mcp"
+    }
+  }
+}
+```
+
+### Alternative: Run locally via `uvx`
+
+```json
+{
+  "mcpServers": {
+    "globkurier": {
+      "command": "uvx",
+      "args": ["globkurier-api-mcp"]
+    }
+  }
+}
+```
+
+Paste the configuration into your MCP client settings file:
+
+| Client | Settings file |
+|---|---|
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
+| **Cursor** | `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally |
+| **Cline** | Extension settings in VS Code |
+
+## Available Tools
+
+| Tool | Description |
+|---|---|
+| `get_shipment_status` | Track a shipment by order number |
+| `search_products` | Search shipping products (DPD, InPost, DHL, FedEx, UPS, GLS and more) |
+| `get_product_addons` | Get available add-ons for a product |
+| `get_search_url` | Generate a purchase link for a shipment |
+
+## Available Resources
+
+| Resource | Description |
+|---|---|
+| `globkurier://countries` | List of supported countries |
+| `globkurier://countries/{iso_code}` | Country details by ISO code |
+
+---
+
+For developer documentation see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT
+
+## Author
+
+it@globkurier.pl

globkurier_api_mcp-0.2.0/README.md

@@ -0,0 +1,71 @@
+<!-- mcp-name: io.github.globkurier-pl/mcp-server -->
+
+# GlobKurier MCP Server
+
+> [Polska wersja dokumentacji](./README.pl.md)
+
+[Model Context Protocol](https://modelcontextprotocol.io/) server for the [GlobKurier](https://www.globkurier.pl) API. Enables AI assistants (Claude, Cursor, Cline and others) to track shipments, search shipping products and generate purchase links.
+
+## Installation
+
+### Recommended: Hosted server (no local installation)
+
+```json
+{
+  "mcpServers": {
+    "globkurier": {
+      "type": "http",
+      "url": "https://mcp.globkurier.pl/mcp"
+    }
+  }
+}
+```
+
+### Alternative: Run locally via `uvx`
+
+```json
+{
+  "mcpServers": {
+    "globkurier": {
+      "command": "uvx",
+      "args": ["globkurier-api-mcp"]
+    }
+  }
+}
+```
+
+Paste the configuration into your MCP client settings file:
+
+| Client | Settings file |
+|---|---|
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
+| **Cursor** | `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally |
+| **Cline** | Extension settings in VS Code |
+
+## Available Tools
+
+| Tool | Description |
+|---|---|
+| `get_shipment_status` | Track a shipment by order number |
+| `search_products` | Search shipping products (DPD, InPost, DHL, FedEx, UPS, GLS and more) |
+| `get_product_addons` | Get available add-ons for a product |
+| `get_search_url` | Generate a purchase link for a shipment |
+
+## Available Resources
+
+| Resource | Description |
+|---|---|
+| `globkurier://countries` | List of supported countries |
+| `globkurier://countries/{iso_code}` | Country details by ISO code |
+
+---
+
+For developer documentation see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT
+
+## Author
+
+it@globkurier.pl

globkurier_api_mcp-0.2.0/globkurier_api_mcp.egg-info/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: globkurier-api-mcp
+Version: 0.2.0
+Summary: MCP server for GlobKurier API - Hexagonal Architecture with CQRS
+Author-email: GlobKurier <it@globkurier.pl>
+License: MIT
+Project-URL: Homepage, https://github.com/GlobKurier-pl/mcp-server
+Project-URL: Repository, https://github.com/GlobKurier-pl/mcp-server
+Project-URL: Documentation, https://github.com/GlobKurier-pl/mcp-server#readme
+Keywords: mcp,shipping,logistics,globkurier,dpd,inpost,courier
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+
+<!-- mcp-name: io.github.globkurier-pl/mcp-server -->
+
+# GlobKurier MCP Server
+
+> [Polska wersja dokumentacji](./README.pl.md)
+
+[Model Context Protocol](https://modelcontextprotocol.io/) server for the [GlobKurier](https://www.globkurier.pl) API. Enables AI assistants (Claude, Cursor, Cline and others) to track shipments, search shipping products and generate purchase links.
+
+## Installation
+
+### Recommended: Hosted server (no local installation)
+
+```json
+{
+  "mcpServers": {
+    "globkurier": {
+      "type": "http",
+      "url": "https://mcp.globkurier.pl/mcp"
+    }
+  }
+}
+```
+
+### Alternative: Run locally via `uvx`
+
+```json
+{
+  "mcpServers": {
+    "globkurier": {
+      "command": "uvx",
+      "args": ["globkurier-api-mcp"]
+    }
+  }
+}
+```
+
+Paste the configuration into your MCP client settings file:
+
+| Client | Settings file |
+|---|---|
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
+| **Cursor** | `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally |
+| **Cline** | Extension settings in VS Code |
+
+## Available Tools
+
+| Tool | Description |
+|---|---|
+| `get_shipment_status` | Track a shipment by order number |
+| `search_products` | Search shipping products (DPD, InPost, DHL, FedEx, UPS, GLS and more) |
+| `get_product_addons` | Get available add-ons for a product |
+| `get_search_url` | Generate a purchase link for a shipment |
+
+## Available Resources
+
+| Resource | Description |
+|---|---|
+| `globkurier://countries` | List of supported countries |
+| `globkurier://countries/{iso_code}` | Country details by ISO code |
+
+---
+
+For developer documentation see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT
+
+## Author
+
+it@globkurier.pl

globkurier_api_mcp-0.2.0/globkurier_api_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,68 @@
+README.md
+pyproject.toml
+globkurier_api_mcp.egg-info/PKG-INFO
+globkurier_api_mcp.egg-info/SOURCES.txt
+globkurier_api_mcp.egg-info/dependency_links.txt
+globkurier_api_mcp.egg-info/entry_points.txt
+globkurier_api_mcp.egg-info/requires.txt
+globkurier_api_mcp.egg-info/top_level.txt
+globkurier_mcp/__init__.py
+globkurier_mcp/__main__.py
+globkurier_mcp/main.py
+globkurier_mcp/application/__init__.py
+globkurier_mcp/application/bus/__init__.py
+globkurier_mcp/application/bus/dispatcher.py
+globkurier_mcp/application/commands/__init__.py
+globkurier_mcp/application/dto/__init__.py
+globkurier_mcp/application/dto/countries_dto.py
+globkurier_mcp/application/dto/product_dto.py
+globkurier_mcp/application/dto/shipping_dto.py
+globkurier_mcp/application/queries/__init__.py
+globkurier_mcp/application/queries/get_countries.py
+globkurier_mcp/application/queries/get_product_addons.py
+globkurier_mcp/application/queries/get_prompts.py
+globkurier_mcp/application/queries/get_search_url.py
+globkurier_mcp/application/queries/get_shipment_status.py
+globkurier_mcp/application/queries/search_products.py
+globkurier_mcp/config/__init__.py
+globkurier_mcp/config/settings.py
+globkurier_mcp/core/__init__.py
+globkurier_mcp/core/countries/__init__.py
+globkurier_mcp/core/countries/models.py
+globkurier_mcp/core/countries/ports.py
+globkurier_mcp/core/products/__init__.py
+globkurier_mcp/core/products/models.py
+globkurier_mcp/core/products/ports.py
+globkurier_mcp/core/prompts/__init__.py
+globkurier_mcp/core/prompts/models.py
+globkurier_mcp/core/prompts/ports.py
+globkurier_mcp/core/shipping/__init__.py
+globkurier_mcp/core/shipping/models.py
+globkurier_mcp/core/shipping/ports.py
+globkurier_mcp/core/shipping/services.py
+globkurier_mcp/infrastructure/__init__.py
+globkurier_mcp/infrastructure/cache/__init__.py
+globkurier_mcp/infrastructure/cache/cached_country_repository.py
+globkurier_mcp/infrastructure/http/__init__.py
+globkurier_mcp/infrastructure/http/countries_client.py
+globkurier_mcp/infrastructure/http/globkurier_client.py
+globkurier_mcp/infrastructure/http/products_client.py
+globkurier_mcp/infrastructure/logging/__init__.py
+globkurier_mcp/infrastructure/logging/config.py
+globkurier_mcp/infrastructure/mcp/__init__.py
+globkurier_mcp/infrastructure/mcp/server.py
+globkurier_mcp/infrastructure/mcp/prompts/__init__.py
+globkurier_mcp/infrastructure/mcp/prompts/prompt_registry.py
+globkurier_mcp/infrastructure/mcp/tools/__init__.py
+globkurier_mcp/infrastructure/mcp/tools/get_countries_tool.py
+globkurier_mcp/infrastructure/mcp/tools/get_product_addons_tool.py
+globkurier_mcp/infrastructure/mcp/tools/get_search_url_tool.py
+globkurier_mcp/infrastructure/mcp/tools/search_products_tool.py
+globkurier_mcp/infrastructure/mcp/tools/shipment_status_tool.py
+globkurier_mcp/infrastructure/prompts/__init__.py
+globkurier_mcp/infrastructure/prompts/json_prompt_repository.py
+tests/test_domain_models.py
+tests/test_prompts_domain_models.py
+tests/test_prompts_query_handler.py
+tests/test_prompts_repository.py
+tests/test_query_handler.py

globkurier_api_mcp-0.2.0/globkurier_api_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

globkurier_api_mcp-0.2.0/globkurier_api_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+globkurier-mcp = globkurier_mcp:main

globkurier_api_mcp-0.2.0/globkurier_api_mcp.egg-info/requires.txt

@@ -0,0 +1,5 @@
+fastmcp>=2.0.0
+httpx>=0.27.0
+python-dotenv>=1.0.0
+pydantic>=2.0.0
+pydantic-settings>=2.0.0

globkurier_api_mcp-0.2.0/globkurier_api_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+globkurier_mcp

globkurier_api_mcp-0.2.0/globkurier_mcp/__init__.py

@@ -0,0 +1,16 @@
+"""GlobKurier MCP Server - Hexagonal Architecture Implementation.
+
+This package implements a Model Context Protocol (MCP) server for GlobKurier API
+using Clean Architecture and CQRS principles.
+
+Architecture layers:
+- core: Domain models, value objects, and ports (business logic)
+- application: Use cases, DTOs, queries, commands, and bus (orchestration)
+- infrastructure: HTTP clients, MCP tools, external adapters (implementation details)
+- config: Settings and configuration
+"""
+
+from globkurier_mcp.main import main
+
+__version__ = "0.2.0"
+__all__ = ["main"]

globkurier_api_mcp-0.2.0/globkurier_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running the package as a module."""
+
+from globkurier_mcp.main import main
+
+if __name__ == "__main__":
+    main()

globkurier_api_mcp-0.2.0/globkurier_mcp/application/__init__.py

@@ -0,0 +1 @@
+# Application layer package

globkurier_api_mcp-0.2.0/globkurier_mcp/application/bus/__init__.py

@@ -0,0 +1,3 @@
+from globkurier_mcp.application.bus.dispatcher import QueryBus, create_query_bus
+
+__all__ = ["QueryBus", "create_query_bus"]

globkurier_api_mcp-0.2.0/globkurier_mcp/application/bus/dispatcher.py

@@ -0,0 +1,112 @@
+from collections.abc import Callable
+from typing import Any, TypeVar, cast
+
+from globkurier_mcp.application.queries.get_countries import (
+    GetCountriesQuery,
+    GetCountriesQueryHandler,
+    GetCountryByIsoQuery,
+    GetCountryByIsoQueryHandler,
+)
+from globkurier_mcp.application.queries.get_product_addons import (
+    GetProductAddonsQuery,
+    GetProductAddonsQueryHandler,
+)
+from globkurier_mcp.application.queries.get_prompts import (
+    GetAllPromptsQuery,
+    GetAllPromptsQueryHandler,
+    GetPromptByNameQuery,
+    GetPromptByNameQueryHandler,
+)
+from globkurier_mcp.application.queries.get_search_url import (
+    GetSearchUrlQuery,
+    GetSearchUrlQueryHandler,
+)
+from globkurier_mcp.application.queries.get_shipment_status import (
+    GetShipmentStatusQuery,
+    GetShipmentStatusQueryHandler,
+)
+from globkurier_mcp.application.queries.search_products import (
+    SearchProductsQuery,
+    SearchProductsQueryHandler,
+)
+
+TQuery = TypeVar("TQuery")
+TResult = TypeVar("TResult")
+
+
+class QueryBus:
+    """Simple query bus implementing CQRS pattern.
+
+    Routes queries to their respective handlers.
+    In a larger application, this could be replaced with a more
+    sophisticated implementation (e.g., using dependency injection).
+    """
+
+    def __init__(self) -> None:
+        self._handlers: dict[type, Callable[[Any], Any]] = {}
+
+    def register(self, query_type: type[TQuery], handler: Callable[[TQuery], TResult]) -> None:
+        """Register a query handler.
+
+        Args:
+            query_type: The type of query this handler processes
+            handler: The handler function/method
+        """
+        self._handlers[query_type] = handler
+
+    async def execute(self, query: TQuery) -> TResult:
+        """Execute a query by dispatching to registered handler.
+
+        Args:
+            query: The query to execute
+
+        Returns:
+            The result from the handler
+
+        Raises:
+            ValueError: If no handler is registered for this query type
+        """
+        query_type = type(query)
+        handler = self._handlers.get(query_type)
+
+        if handler is None:
+            raise ValueError(f"No handler registered for query type: {query_type.__name__}")
+
+        return cast(TResult, await handler(query))
+
+
+def create_query_bus(
+    get_shipment_status_handler: GetShipmentStatusQueryHandler,
+    get_countries_handler: GetCountriesQueryHandler,
+    get_country_by_iso_handler: GetCountryByIsoQueryHandler,
+    get_all_prompts_handler: GetAllPromptsQueryHandler,
+    get_prompt_by_name_handler: GetPromptByNameQueryHandler,
+    search_products_handler: SearchProductsQueryHandler,
+    get_product_addons_handler: GetProductAddonsQueryHandler,
+    get_search_url_handler: GetSearchUrlQueryHandler,
+) -> QueryBus:
+    """Factory function to create and configure the query bus.
+
+    Args:
+        get_shipment_status_handler: Handler for shipment status queries
+        get_countries_handler: Handler for countries list queries
+        get_country_by_iso_handler: Handler for single country by ISO code queries
+        get_all_prompts_handler: Handler for all prompts queries
+        get_prompt_by_name_handler: Handler for single prompt by name queries
+        search_products_handler: Handler for product search queries
+        get_product_addons_handler: Handler for product addons queries
+        get_search_url_handler: Handler for search URL generation queries
+
+    Returns:
+        Configured QueryBus instance
+    """
+    bus = QueryBus()
+    bus.register(GetShipmentStatusQuery, get_shipment_status_handler.handle)
+    bus.register(GetCountriesQuery, get_countries_handler.handle)
+    bus.register(GetCountryByIsoQuery, get_country_by_iso_handler.handle)
+    bus.register(GetAllPromptsQuery, get_all_prompts_handler.handle)
+    bus.register(GetPromptByNameQuery, get_prompt_by_name_handler.handle)
+    bus.register(SearchProductsQuery, search_products_handler.handle)
+    bus.register(GetProductAddonsQuery, get_product_addons_handler.handle)
+    bus.register(GetSearchUrlQuery, get_search_url_handler.handle)
+    return bus

globkurier_api_mcp-0.2.0/globkurier_mcp/application/commands/__init__.py

@@ -0,0 +1,2 @@
+# Commands package - placeholder for future write operations
+# Example: CreateShipmentCommand, UpdateShipmentCommand, etc.

globkurier_api_mcp-0.2.0/globkurier_mcp/application/dto/__init__.py

@@ -0,0 +1,3 @@
+from globkurier_mcp.application.dto.shipping_dto import ShipmentStatusDto, TrackingEventDto
+
+__all__ = ["ShipmentStatusDto", "TrackingEventDto"]

globkurier_api_mcp-0.2.0/globkurier_mcp/application/dto/countries_dto.py

@@ -0,0 +1,26 @@
+"""DTOs for countries bounded context."""
+
+from pydantic import BaseModel, Field
+
+
+class CountryDto(BaseModel):
+    """DTO for a single country."""
+
+    id: int = Field(..., description="Unique country identifier")
+    name: str = Field(..., description="Country name")
+    iso_code: str = Field(..., description="ISO 3166-1 alpha-2 code")
+    is_ue_member: bool = Field(..., description="Whether country is EU member")
+    is_road_transport_available: bool = Field(..., description="Road transport availability")
+    has_states: bool = Field(..., description="Whether country has states/provinces")
+    has_post_codes: bool = Field(..., description="Whether country uses postal codes")
+    post_code_format: str | None = Field(None, description="Postal code format pattern")
+    phone_prefix: str = Field(..., description="International phone prefix")
+    post_code_samples: str | None = Field(None, description="Example postal codes")
+
+
+class CountriesListDto(BaseModel):
+    """DTO for list of countries."""
+
+    countries: list[CountryDto] = Field(..., description="List of available countries")
+    total_count: int = Field(..., description="Total number of countries")
+    cached: bool = Field(..., description="Whether data was served from cache")

globkurier_api_mcp-0.2.0/globkurier_mcp/application/dto/product_dto.py

@@ -0,0 +1,138 @@
+"""DTOs for product search results.
+
+These DTOs are used to transfer data from application layer to presentation layer (MCP).
+Domain models are never exposed directly.
+"""
+
+from decimal import Decimal
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TransportDto(BaseModel):
+    """Transport information DTO."""
+
+    code: str
+    name: str
+
+
+class CollectionTypeOptionDto(BaseModel):
+    """Collection type option DTO."""
+
+    key: str
+    trans: str
+    image: str
+
+
+class DeliveryTypeOptionDto(BaseModel):
+    """Delivery type option DTO."""
+
+    key: str
+    trans: str
+    image: str
+
+
+class ProductDto(BaseModel):
+    """Product DTO for API responses."""
+
+    id: int
+    name: str
+    carrier_name: str = Field(alias="carrierName")
+    service_code: str | None = Field(alias="serviceCode")
+    net_price: Decimal = Field(alias="netPrice")
+    gross_price: Decimal = Field(alias="grossPrice")
+    net_price_standard: Decimal | None = Field(None, alias="netPriceStandard")
+    gross_price_standard: Decimal | None = Field(None, alias="grossPriceStandard")
+    currency: str
+    units: int
+    protocol_available: bool = Field(alias="protocolAvailable")
+    package_type: str = Field(alias="packageType")
+    package_name: str = Field(alias="packageName")
+    transport: TransportDto
+    for_company: bool = Field(alias="forCompany")
+    carrier_logo_link: str = Field(alias="carrierLogoLink")
+    discount_code_allowed: bool = Field(alias="discountCodeAllowed")
+    average_delivery: int | None = Field(alias="averageDelivery")
+    delivery_time_type: str = Field(alias="deliveryTimeType")
+    details_link: str | None = Field(alias="detailsLink")
+    promo: str | None = None
+    has_country_zone_routing: bool = Field(alias="hasCountryZoneRouting")
+    on_demand_delivery_point_required: bool = Field(
+        alias="onDemandDeliveryPointRequired"
+    )
+    custom_document_type: str | None = Field(None, alias="customDocumentType")
+    labels: list[str]
+    collection_types: list[str] = Field(alias="collectionTypes")
+    addons_categories: list[str] = Field(alias="addonsCategories")
+    delivery_types: list[str] = Field(alias="deliveryTypes")
+    collection_type_options: list[CollectionTypeOptionDto] = Field(
+        alias="collectionTypeOptions"
+    )
+    delivery_type_options: list[DeliveryTypeOptionDto] = Field(
+        alias="deliveryTypeOptions"
+    )
+    carrier_id: int = Field(alias="carrierId")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class ProductSearchResultDto(BaseModel):
+    """DTO for product search results grouped by delivery time."""
+
+    fast: list[ProductDto]
+    superfast: list[ProductDto]
+    noon: list[ProductDto]
+    morning: list[ProductDto]
+    standard: list[ProductDto]
+    total_products: int = Field(alias="totalProducts")
+    cheapest_product_id: int | None = Field(None, alias="cheapestProductId")
+    fastest_product_id: int | None = Field(None, alias="fastestProductId")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class AddonDto(BaseModel):
+    """Addon DTO for API responses."""
+
+    id: int
+    addon_name: str = Field(alias="addonName")
+    description: str | None = None
+    attributes: dict[str, Any] | None = None
+    addon_logo: str | None = Field(None, alias="addonLogo")
+    price: Decimal
+    price_gross: Decimal = Field(alias="priceGross")
+    price_description: str | None = Field(None, alias="priceDescription")
+    quantity: int = 1
+    currency: str
+    category: str
+    is_required: bool = Field(alias="isRequired")
+    insurance_required: bool = Field(alias="insuranceRequired")
+    min_value: Decimal | None = Field(None, alias="minValue")
+    max_value: Decimal | None = Field(None, alias="maxValue")
+    value_currency: str | None = Field(None, alias="valueCurrency")
+    days_to_return: int | None = Field(None, alias="daysToReturn")
+    verification_required: bool = Field(alias="verificationRequired")
+    in_price: bool = Field(alias="inPrice")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class GetAddonsResultDto(BaseModel):
+    """DTO for product addons result."""
+
+    addons: list[AddonDto]
+    required_alternative_addons_groups: list[list[int]] = Field(
+        alias="requiredAlternativeAddonsGroups"
+    )
+    total_addons: int = Field(alias="totalAddons")
+    required_addons_count: int = Field(alias="requiredAddonsCount")
+    optional_addons_count: int = Field(alias="optionalAddonsCount")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class SearchUrlDto(BaseModel):
+    """DTO for GlobKurier search page URL."""
+
+    url: str = Field(..., description="URL to GlobKurier search page with pre-filled parameters")