python-getpaid-simulator 3.0.0__py3-none-any.whl

getpaid_simulator/__init__.py

@@ -0,0 +1,3 @@
+"""Payment gateway simulator for testing the python-getpaid ecosystem."""
+
+__version__ = "3.0.0"

getpaid_simulator/__main__.py

@@ -0,0 +1,112 @@
+"""CLI entry point for getpaid-simulator."""
+
+import argparse
+import sys
+
+import uvicorn
+
+from getpaid_simulator import __version__
+from getpaid_simulator.app import create_app
+from getpaid_simulator.core.config import SimulatorConfig
+from getpaid_simulator.plugins import load_provider_plugins
+
+
+def _print_startup_banner(
+    config: SimulatorConfig,
+    loaded_providers: list[str],
+    failed_providers: list[str],
+) -> None:
+    """Print startup banner with discovered providers and dashboard URL.
+
+    Args:
+        config: Simulator configuration.
+        loaded_providers: Display names for loaded simulator plugins.
+        failed_providers: Slugs for failed plugins.
+    """
+    providers_str = ", ".join(loaded_providers) if loaded_providers else "none"
+    failed_str = ", ".join(failed_providers) if failed_providers else "none"
+
+    dashboard_url = f"http://{config.host}:{config.port}/sim/"
+    status_label = "DEGRADED" if failed_providers else "READY"
+
+    banner = f"""
+╔══════════════════════════════════════╗
+║  🔶 getpaid-simulator v{__version__:<18}║
+║  ⚠  SIMULATOR — NOT REAL PAYMENTS   ║
+║  Status: {status_label:<27}║
+║  Providers: {providers_str:<23}║
+║  Failed: {failed_str:<26}║
+║  Dashboard: {dashboard_url:<23}║
+╚══════════════════════════════════════╝
+"""
+    print(banner)
+
+
+def main() -> None:
+    """CLI entry point for getpaid-simulator."""
+    parser = argparse.ArgumentParser(
+        description="GetPaid Payment Gateway Simulator",
+        prog="getpaid-simulator",
+    )
+    parser.add_argument(
+        "--host",
+        default=None,
+        help="Server host (default: 0.0.0.0)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help="Server port (default: 9000)",
+    )
+    parser.add_argument(
+        "--log-level",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        default=None,
+        help="Logging level (default: INFO)",
+    )
+    parser.add_argument(
+        "--plugin-failure-mode",
+        choices=["strict", "warn"],
+        default=None,
+        help="Plugin failure mode (default: warn)",
+    )
+
+    args = parser.parse_args()
+
+    # Load config from environment variables
+    config = SimulatorConfig.from_env()
+
+    # Override with CLI arguments if provided
+    if args.host is not None:
+        config.host = args.host
+    if args.port is not None:
+        config.port = args.port
+    if args.log_level is not None:
+        config.log_level = args.log_level
+    if args.plugin_failure_mode is not None:
+        config.plugin_failure_mode = args.plugin_failure_mode
+
+    plugin_load_result = load_provider_plugins(config)
+    _print_startup_banner(
+        config,
+        loaded_providers=[
+            plugin.display_name for plugin in plugin_load_result.loaded_plugins
+        ],
+        failed_providers=[
+            failure.slug for failure in plugin_load_result.failed_plugins
+        ],
+    )
+
+    # Create and run app
+    app = create_app(config, plugin_load_result)
+    uvicorn.run(
+        app,
+        host=config.host,
+        port=config.port,
+        log_level=config.log_level.lower(),
+    )
+
+
+if __name__ == "__main__":
+    main()

getpaid_simulator/app.py

@@ -0,0 +1,132 @@
+"""Litestar application for payment gateway simulator."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from litestar import Litestar
+from litestar import get
+from litestar.contrib.jinja import JinjaTemplateEngine
+from litestar.datastructures import State
+from litestar.static_files import create_static_files_router
+from litestar.template.config import TemplateConfig
+
+from getpaid_simulator.core.config import SimulatorConfig
+from getpaid_simulator.core.state import InvalidTransitionError
+from getpaid_simulator.core.state import PaymentStateMachine
+from getpaid_simulator.core.storage import SimulatorStorage
+from getpaid_simulator.core.webhooks import WebhookTransport
+from getpaid_simulator.plugins import PluginLoadResult
+from getpaid_simulator.plugins import load_provider_plugins
+from getpaid_simulator.ui import routes as ui_routes
+
+
+logger = logging.getLogger(__name__)
+
+
+@get("/")
+async def health(state: State) -> dict[str, object]:
+    """Health check endpoint."""
+    loaded_plugins = list(state.loaded_plugins)
+    failed_plugins = [failure.slug for failure in state.failed_plugins]
+    status = "degraded" if failed_plugins else "ok"
+    return {
+        "status": status,
+        "service": "getpaid-simulator",
+        "loadedProviders": loaded_plugins,
+        "failedProviders": failed_plugins,
+    }
+
+
+@get("/sim/status")
+async def simulator_status(state: State) -> dict[str, object]:
+    """Detailed status endpoint for the simulator host."""
+    return {
+        "status": "degraded" if state.failed_plugins else "ok",
+        "loadedProviders": [
+            {
+                "slug": slug,
+                "displayName": plugin.display_name,
+            }
+            for slug, plugin in state.loaded_plugins.items()
+        ],
+        "failedProviders": [
+            {
+                "slug": failure.slug,
+                "stage": failure.stage,
+                "error": failure.error,
+            }
+            for failure in state.failed_plugins
+        ],
+    }
+
+
+def create_app(
+    config: SimulatorConfig | None = None,
+    plugin_load_result: PluginLoadResult | None = None,
+) -> Litestar:
+    config = config or SimulatorConfig.from_env()
+    plugin_load_result = plugin_load_result or load_provider_plugins(config)
+    loaded_plugins = {
+        plugin.slug: plugin for plugin in plugin_load_result.loaded_plugins
+    }
+    state_machine = PaymentStateMachine(SimulatorStorage())
+    for plugin in plugin_load_result.loaded_plugins:
+        state_machine.register_provider(plugin.slug, plugin.transitions)
+
+    route_handlers = [health, simulator_status, ui_routes.dashboard]
+    for plugin in plugin_load_result.loaded_plugins:
+        route_handlers.extend(plugin.api_handlers)
+        route_handlers.extend(plugin.ui_handlers)
+
+    loaded_display_names = [
+        plugin.display_name for plugin in plugin_load_result.loaded_plugins
+    ]
+    failed_slugs = [
+        failure.slug for failure in plugin_load_result.failed_plugins
+    ]
+    if loaded_display_names:
+        logger.info(
+            "Loaded simulator plugins: %s",
+            ", ".join(loaded_display_names),
+        )
+    else:
+        logger.info("Loaded simulator plugins: none")
+    if failed_slugs:
+        logger.warning(
+            "Failed simulator plugins: %s",
+            ", ".join(failed_slugs),
+        )
+
+    storage = state_machine.storage
+    webhook_transport = WebhookTransport(
+        timeout=config.webhook_timeout,
+        max_retries=config.webhook_max_retries,
+    )
+    state = State(
+        {
+            "storage": storage,
+            "state_machine": state_machine,
+            "webhook_transport": webhook_transport,
+            "config": config,
+            "loaded_plugins": loaded_plugins,
+            "provider_configs": plugin_load_result.provider_configs,
+            "failed_plugins": plugin_load_result.failed_plugins,
+            "invalid_transition_error": InvalidTransitionError,
+        }
+    )
+    static_files_router = create_static_files_router(
+        path="/static",
+        directories=[Path(__file__).parent / "ui" / "static"],
+    )
+
+    return Litestar(
+        route_handlers=[*route_handlers, static_files_router],
+        state=state,
+        template_config=TemplateConfig(
+            engine=JinjaTemplateEngine(
+                directory=Path(__file__).parent / "ui" / "templates"
+            )
+        ),
+    )

getpaid_simulator/core/__init__.py

@@ -0,0 +1 @@
+"""Core simulator components."""

getpaid_simulator/core/config.py

@@ -0,0 +1,57 @@
+"""Configuration system for getpaid-simulator."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Literal
+
+
+PluginFailureMode = Literal["strict", "warn"]
+
+
+@dataclass
+class SimulatorConfig:
+    """Configuration for the payment simulator.
+
+    All configuration values can be overridden via environment variables
+    with the SIMULATOR_ prefix.
+    """
+
+    host: str = "0.0.0.0"
+    port: int = 9000
+    webhook_timeout: float = 5.0
+    webhook_max_retries: int = 3
+    log_level: str = "INFO"
+    plugin_failure_mode: PluginFailureMode = "warn"
+
+    @classmethod
+    def from_env(cls) -> "SimulatorConfig":
+        """Load configuration from environment variables.
+
+        Environment variables use the SIMULATOR_ prefix (e.g.,
+        SIMULATOR_PORT=8080 overrides the port default).
+
+        Returns:
+            SimulatorConfig: Configuration instance with env var overrides.
+        """
+        plugin_failure_mode = os.environ.get(
+            "SIMULATOR_PLUGIN_FAILURE_MODE", "warn"
+        )
+        if plugin_failure_mode not in {"strict", "warn"}:
+            raise ValueError(
+                "SIMULATOR_PLUGIN_FAILURE_MODE must be 'strict' or 'warn'"
+            )
+
+        return cls(
+            host=os.environ.get("SIMULATOR_HOST", "0.0.0.0"),
+            port=int(os.environ.get("SIMULATOR_PORT", "9000")),
+            webhook_timeout=float(
+                os.environ.get("SIMULATOR_WEBHOOK_TIMEOUT", "5.0")
+            ),
+            webhook_max_retries=int(
+                os.environ.get("SIMULATOR_WEBHOOK_MAX_RETRIES", "3")
+            ),
+            log_level=os.environ.get("SIMULATOR_LOG_LEVEL", "INFO"),
+            plugin_failure_mode=plugin_failure_mode,
+        )

getpaid_simulator/core/discovery.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from getpaid_simulator.core.config import SimulatorConfig
+from getpaid_simulator.plugins import load_provider_plugins
+
+
+ENTRY_POINT_GROUP = "getpaid.simulator.providers"
+
+
+def discover_providers() -> list[str]:
+    result = load_provider_plugins(SimulatorConfig())
+    return [plugin.slug for plugin in result.loaded_plugins]

getpaid_simulator/core/state.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any
+
+from getpaid_simulator.core.storage import SimulatorStorage
+
+
+class InvalidTransitionError(Exception):
+    def __init__(self, current: str, requested: str):
+        self.current = current
+        self.requested = requested
+        self.error_response = {
+            "status": {
+                "statusCode": "ERROR_VALUE_INVALID",
+                "statusDesc": (
+                    f"Cannot transition from {current} to {requested}"
+                ),
+            }
+        }
+        super().__init__(self.error_response["status"]["statusDesc"])
+
+
+class PaymentStateMachine:
+    def __init__(
+        self,
+        storage: SimulatorStorage,
+        transitions: dict[str, set[str]] | None = None,
+    ):
+        self.storage = storage
+        self._default_transitions = transitions or {}
+        self._provider_transitions: dict[str, dict[str, set[str]]] = {}
+
+    def register_provider(
+        self,
+        provider_slug: str,
+        transitions: dict[str, set[str]],
+    ) -> None:
+        self._provider_transitions[provider_slug] = transitions
+
+    def transition(self, order_id: str, new_status: str) -> dict[str, Any]:
+        order = self.storage.get_order(order_id)
+        if order is None:
+            raise KeyError(order_id)
+
+        provider = order.get("provider", "payu")
+        transitions = self._provider_transitions.get(
+            provider, self._default_transitions
+        )
+
+        current_status = str(order.get("status", "NEW"))
+        if new_status not in transitions.get(current_status, set()):
+            raise InvalidTransitionError(current_status, new_status)
+
+        self.storage.update_order(order_id, status=new_status)
+        updated_order = self.storage.get_order(order_id)
+        if updated_order is None:
+            raise KeyError(order_id)
+        return updated_order

getpaid_simulator/core/storage.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from copy import deepcopy
+from datetime import UTC
+from datetime import datetime
+from datetime import timedelta
+from decimal import Decimal
+from typing import Any
+from uuid import uuid4
+
+
+def _centify(value: Any) -> Any:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, Decimal):
+        return str(int(value))
+    if isinstance(value, list):
+        return [_centify(item) for item in value]
+    if isinstance(value, dict):
+        return {key: _centify(item) for key, item in value.items()}
+    return value
+
+
+def _centify_dict(data: dict[str, Any]) -> dict[str, Any]:
+    return _centify(data)
+
+
+class SimulatorStorage:
+    def __init__(self) -> None:
+        self._orders: dict[str, dict[str, Any]] = {}
+        self._tokens: dict[str, dict[str, Any]] = {}
+        self._refunds: defaultdict[str, list[dict[str, Any]]] = defaultdict(
+            list
+        )
+
+    def create_order(
+        self,
+        data: dict[str, Any] | None = None,
+        *,
+        provider: str | None = None,
+        total_amount: int | str | Decimal | None = None,
+        currency: str | None = None,
+        description: str | None = None,
+        notify_url: str = "",
+        continue_url: str | None = None,
+        buyer_email: str | None = None,
+    ) -> str:
+        order_id = uuid4().hex
+        if data is None:
+            if provider is None:
+                raise TypeError(
+                    "provider is required when data is not provided"
+                )
+            if total_amount is None:
+                raise TypeError(
+                    "total_amount is required when data is not provided"
+                )
+            if currency is None:
+                raise TypeError(
+                    "currency is required when data is not provided"
+                )
+            if description is None:
+                raise TypeError(
+                    "description is required when data is not provided"
+                )
+
+            order_payload: dict[str, Any] = {
+                "provider": provider,
+                "status": "NEW",
+                "totalAmount": total_amount,
+                "currencyCode": currency,
+                "description": description,
+                "continueUrl": continue_url,
+                "buyer": {},
+            }
+            if notify_url:
+                order_payload["notifyUrl"] = notify_url
+            if buyer_email:
+                order_payload["buyer"] = {"email": buyer_email}
+        else:
+            order_payload = deepcopy(data)
+            order_payload["provider"] = provider or str(
+                order_payload.get("provider", "payu")
+            )
+
+        order_data = _centify_dict(order_payload)
+        order_data["id"] = order_id
+        self._orders[order_id] = order_data
+        return order_id
+
+    def get_order(self, order_id: str) -> dict[str, Any] | None:
+        order = self._orders.get(order_id)
+        if order is None:
+            return None
+        return deepcopy(order)
+
+    def update_order(self, order_id: str, **updates) -> None:
+        if order_id not in self._orders:
+            raise KeyError(order_id)
+        self._orders[order_id].update(_centify(deepcopy(updates)))
+
+    def list_orders(self) -> list[dict[str, Any]]:
+        return [deepcopy(order) for order in self._orders.values()]
+
+    def list_orders_by_provider(self, provider: str) -> list[dict[str, Any]]:
+        return [
+            deepcopy(order)
+            for order in self._orders.values()
+            if order.get("provider") == provider
+        ]
+
+    def create_token(
+        self, pos_id: str, expires_in: int = 3600
+    ) -> dict[str, Any]:
+        access_token = uuid4().hex
+        self._tokens[access_token] = {
+            "pos_id": pos_id,
+            "expires_at": datetime.now(UTC) + timedelta(seconds=expires_in),
+        }
+        return {"access_token": access_token, "expires_in": expires_in}
+
+    def validate_token(self, token: str) -> bool:
+        token_data = self._tokens.get(token)
+        if token_data is None:
+            return False
+        return datetime.now(UTC) < token_data["expires_at"]
+
+    def create_refund(self, order_id: str, data: dict[str, Any]) -> str:
+        refund_id = uuid4().hex
+        refund_data = _centify_dict(deepcopy(data))
+        refund_data["id"] = refund_id
+        refund_data["order_id"] = order_id
+        self._refunds[order_id].append(refund_data)
+        return refund_id
+
+    def get_refunds(self, order_id: str) -> list[dict[str, Any]]:
+        return [deepcopy(refund) for refund in self._refunds.get(order_id, [])]
+
+    def get_refund(self, refund_id: str) -> dict[str, Any] | None:
+        for refunds in self._refunds.values():
+            for refund in refunds:
+                if refund.get("id") == refund_id:
+                    return deepcopy(refund)
+        return None
+
+    def update_refund(self, refund_id: str, **updates: Any) -> None:
+        for refunds in self._refunds.values():
+            for refund in refunds:
+                if refund.get("id") == refund_id:
+                    refund.update(_centify(deepcopy(updates)))
+                    return
+        raise KeyError(refund_id)

getpaid_simulator/core/webhooks.py

@@ -0,0 +1,60 @@
+"""Generic webhook delivery helpers for simulator plugins."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+import httpx
+
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+class WebhookTransport:
+    """Generic webhook transport with retry handling."""
+
+    def __init__(
+        self,
+        timeout: float = 5.0,
+        retry_delay: float = 0.0,
+        max_retries: int = 1,
+    ) -> None:
+        self.timeout = timeout
+        self.retry_delay = retry_delay
+        self.max_retries = max_retries
+
+    async def deliver(
+        self,
+        *,
+        url: str,
+        body: bytes,
+        headers: Mapping[str, str],
+    ) -> bool:
+        """Send webhook payload with retry handling."""
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            attempts = self.max_retries + 1
+            for attempt in range(attempts):
+                try:
+                    response = await client.post(
+                        url, content=body, headers=headers
+                    )
+                    if 400 <= response.status_code < 500:
+                        return False
+                    if 200 <= response.status_code < 300:
+                        return True
+                    if attempt < attempts - 1:
+                        await asyncio.sleep(self.retry_delay)
+                        continue
+                    return False
+                except (
+                    httpx.ConnectError,
+                    httpx.TimeoutException,
+                    httpx.RequestError,
+                ):
+                    if attempt < attempts - 1:
+                        await asyncio.sleep(self.retry_delay)
+                        continue
+                    return False
+        return False