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

getpaid_simulator/plugins.py

@@ -0,0 +1,216 @@
+"""Plugin loading for simulator provider integrations."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from dataclasses import field
+from importlib.metadata import entry_points
+from typing import Any
+
+from getpaid_simulator.core.config import SimulatorConfig
+from getpaid_simulator.spi import SIMULATOR_PLUGIN_API_VERSION
+from getpaid_simulator.spi import SimulatorProviderPlugin
+
+
+ENTRY_POINT_GROUP = "getpaid.simulator.providers"
+
+
+@dataclass(frozen=True)
+class ProviderLoadFailure:
+    """Structured plugin load failure for logging and UI reporting."""
+
+    slug: str
+    stage: str
+    error: str
+
+
+@dataclass(frozen=True)
+class PluginLoadResult:
+    """Loaded plugins, failures, and validated provider configs."""
+
+    loaded_plugins: tuple[SimulatorProviderPlugin, ...] = ()
+    failed_plugins: tuple[ProviderLoadFailure, ...] = ()
+    provider_configs: dict[str, Mapping[str, Any]] = field(default_factory=dict)
+
+
+class PluginLoadError(RuntimeError):
+    """Raised in strict mode when a simulator plugin cannot be loaded."""
+
+    def __init__(self, failure: ProviderLoadFailure):
+        self.failure = failure
+        super().__init__(
+            f"Failed to load simulator plugin {failure.slug!r} during "
+            f"{failure.stage}: {failure.error}"
+        )
+
+
+def load_provider_plugins(
+    config: SimulatorConfig,
+    env: Mapping[str, str] | None = None,
+) -> PluginLoadResult:
+    """Load simulator provider plugins from entry points."""
+    environment = env or os.environ
+    loaded_plugins: list[SimulatorProviderPlugin] = []
+    failed_plugins: list[ProviderLoadFailure] = []
+    provider_configs: dict[str, Mapping[str, Any]] = {}
+
+    for entry_point in sorted(
+        entry_points(group=ENTRY_POINT_GROUP),
+        key=lambda candidate: candidate.name,
+    ):
+        slug = entry_point.name or "<unknown>"
+
+        try:
+            plugin_factory = entry_point.load()
+        except Exception as exc:
+            _handle_failure(
+                config=config,
+                failed_plugins=failed_plugins,
+                failure=ProviderLoadFailure(
+                    slug=slug,
+                    stage="import",
+                    error=str(exc),
+                ),
+            )
+            continue
+
+        try:
+            plugin = (
+                plugin_factory() if callable(plugin_factory) else plugin_factory
+            )
+        except Exception as exc:
+            _handle_failure(
+                config=config,
+                failed_plugins=failed_plugins,
+                failure=ProviderLoadFailure(
+                    slug=slug,
+                    stage="factory",
+                    error=str(exc),
+                ),
+            )
+            continue
+
+        failure = _validate_plugin(slug, plugin)
+        if failure is not None:
+            _handle_failure(
+                config=config,
+                failed_plugins=failed_plugins,
+                failure=failure,
+            )
+            continue
+
+        normalized_plugin = _normalize_plugin(plugin)
+
+        try:
+            provider_configs[normalized_plugin.slug] = dict(
+                normalized_plugin.load_config(environment)
+            )
+        except Exception as exc:
+            _handle_failure(
+                config=config,
+                failed_plugins=failed_plugins,
+                failure=ProviderLoadFailure(
+                    slug=normalized_plugin.slug,
+                    stage="config",
+                    error=str(exc),
+                ),
+            )
+            continue
+
+        loaded_plugins.append(normalized_plugin)
+
+    return PluginLoadResult(
+        loaded_plugins=tuple(loaded_plugins),
+        failed_plugins=tuple(failed_plugins),
+        provider_configs=provider_configs,
+    )
+
+
+def _validate_plugin(
+    entry_point_slug: str,
+    plugin: object,
+) -> ProviderLoadFailure | None:
+    required_fields = {
+        "api_version",
+        "slug",
+        "display_name",
+        "api_handlers",
+        "ui_handlers",
+        "transitions",
+        "load_config",
+    }
+    missing_fields = [
+        field_name
+        for field_name in sorted(required_fields)
+        if not hasattr(plugin, field_name)
+    ]
+    if missing_fields:
+        return ProviderLoadFailure(
+            slug=entry_point_slug,
+            stage="factory",
+            error=(
+                "plugin object is missing required fields: "
+                f"{', '.join(missing_fields)}"
+            ),
+        )
+
+    plugin_api_version = str(getattr(plugin, "api_version"))
+    plugin_slug = str(getattr(plugin, "slug"))
+    if plugin_api_version != SIMULATOR_PLUGIN_API_VERSION:
+        return ProviderLoadFailure(
+            slug=plugin_slug,
+            stage="compatibility",
+            error=(
+                "plugin API version "
+                f"{plugin_api_version!r} is incompatible with host "
+                f"{SIMULATOR_PLUGIN_API_VERSION!r}"
+            ),
+        )
+
+    if plugin_slug != entry_point_slug:
+        return ProviderLoadFailure(
+            slug=entry_point_slug,
+            stage="compatibility",
+            error=(
+                f"plugin slug {plugin_slug!r} does not match entry point "
+                f"name {entry_point_slug!r}"
+            ),
+        )
+
+    return None
+
+
+def _normalize_plugin(plugin: object) -> SimulatorProviderPlugin:
+    transitions = {
+        str(status): set(next_statuses)
+        for status, next_statuses in dict(
+            getattr(plugin, "transitions")
+        ).items()
+    }
+    authorize_path_template = getattr(plugin, "authorize_path_template", None)
+    if authorize_path_template is not None:
+        authorize_path_template = str(authorize_path_template)
+
+    return SimulatorProviderPlugin(
+        api_version=str(getattr(plugin, "api_version")),
+        slug=str(getattr(plugin, "slug")),
+        display_name=str(getattr(plugin, "display_name")),
+        api_handlers=tuple(getattr(plugin, "api_handlers")),
+        ui_handlers=tuple(getattr(plugin, "ui_handlers")),
+        transitions=transitions,
+        load_config=getattr(plugin, "load_config"),
+        authorize_path_template=authorize_path_template,
+    )
+
+
+def _handle_failure(
+    *,
+    config: SimulatorConfig,
+    failed_plugins: list[ProviderLoadFailure],
+    failure: ProviderLoadFailure,
+) -> None:
+    if config.plugin_failure_mode == "strict":
+        raise PluginLoadError(failure)
+    failed_plugins.append(failure)

getpaid_simulator/spi.py

@@ -0,0 +1,31 @@
+"""Stable plugin API for simulator provider integrations."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+
+SIMULATOR_PLUGIN_API_VERSION = "1"
+
+
+@dataclass(frozen=True)
+class SimulatorProviderPlugin:
+    """Declarative simulator provider plugin descriptor."""
+
+    api_version: str
+    slug: str
+    display_name: str
+    api_handlers: tuple[Any, ...]
+    ui_handlers: tuple[Any, ...]
+    transitions: dict[str, set[str]]
+    load_config: Callable[[Mapping[str, str]], Mapping[str, Any]]
+    authorize_path_template: str | None = None
+
+    def build_authorize_path(self, entity_id: str) -> str | None:
+        """Return the provider-specific authorize URL for dashboard links."""
+        if self.authorize_path_template is None:
+            return None
+        return self.authorize_path_template.format(entity_id=entity_id)

getpaid_simulator/ui/__init__.py

@@ -0,0 +1 @@
+"""UI components."""

getpaid_simulator/ui/routes.py

@@ -0,0 +1,104 @@
+from decimal import Decimal
+from decimal import InvalidOperation
+from typing import Any
+from typing import Optional
+
+from litestar import get
+from litestar.datastructures import State
+from litestar.response import Template
+
+from getpaid_simulator.core.storage import SimulatorStorage
+from getpaid_simulator.plugins import ProviderLoadFailure
+from getpaid_simulator.spi import SimulatorProviderPlugin
+
+
+def _format_amount_for_display(
+    order: dict[str, Any],
+    provider_config: dict[str, Any] | None,
+) -> str:
+    amount_raw = order.get("amount", order.get("totalAmount", 0))
+    currency = str(order.get("currency", order.get("currencyCode", "PLN")))
+    try:
+        amount_value = Decimal(str(amount_raw))
+    except (InvalidOperation, TypeError, ValueError):
+        return str(amount_raw)
+
+    minor_unit_places = _minor_unit_places(provider_config)
+    if minor_unit_places is not None:
+        amount_value /= Decimal(10) ** minor_unit_places
+
+    return f"{amount_value:.2f} {currency}"
+
+
+def _minor_unit_places(provider_config: dict[str, Any] | None) -> int | None:
+    if provider_config is None:
+        return None
+
+    raw_value = provider_config.get("amount_minor_unit_places")
+    if raw_value is None:
+        return None
+
+    try:
+        places = int(raw_value)
+    except (TypeError, ValueError):
+        return None
+
+    if places < 0:
+        return None
+
+    return places
+
+
+@get(["/sim/", "/sim/dashboard"])
+async def dashboard(state: State, provider: Optional[str] = None) -> Template:
+    """Render payments dashboard."""
+    storage: SimulatorStorage = state.storage
+    loaded_plugins: dict[str, SimulatorProviderPlugin] = state.loaded_plugins
+    failed_plugins: tuple[ProviderLoadFailure, ...] = state.failed_plugins
+    if provider:
+        orders_data = storage.list_orders_by_provider(provider)
+    else:
+        orders_data = storage.list_orders()
+
+    provider_filters = [
+        {
+            "slug": slug,
+            "display_name": plugin.display_name,
+        }
+        for slug, plugin in loaded_plugins.items()
+    ]
+
+    orders = []
+    for order in orders_data:
+        provider_slug = str(order.get("provider", "unknown"))
+        plugin = loaded_plugins.get(provider_slug)
+        provider_config = state.provider_configs.get(provider_slug)
+        orders.append(
+            {
+                "id": order["id"],
+                "provider": provider_slug,
+                "provider_display_name": (
+                    plugin.display_name if plugin is not None else provider_slug
+                ),
+                "status": order.get("status", "NEW"),
+                "formatted_amount": _format_amount_for_display(
+                    order,
+                    provider_config,
+                ),
+                "authorize_url": (
+                    plugin.build_authorize_path(str(order["id"]))
+                    if plugin is not None
+                    else None
+                ),
+            }
+        )
+
+    return Template(
+        template_name="dashboard.html",
+        context={
+            "orders": orders,
+            "current_provider": provider,
+            "provider_filters": provider_filters,
+            "failed_plugins": failed_plugins,
+        },
+    )

getpaid_simulator/ui/static/style.css

@@ -0,0 +1,262 @@
+:root {
+  --bg-dark: #0d0d0d;
+  --bg-card: #1a1a1a;
+  --text-main: #e0e0e0;
+  --text-muted: #888888;
+  
+  --amber: #ff9900;
+  --amber-dim: rgba(255, 153, 0, 0.2);
+  
+  --neon-green: #00ff88;
+  --neon-green-dim: rgba(0, 255, 136, 0.2);
+  
+  --neon-red: #ff3344;
+  --neon-red-dim: rgba(255, 51, 68, 0.2);
+  
+  --border-radius: 4px;
+  --font-mono: 'Courier New', Courier, monospace, system-ui;
+}
+
+* {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  background-color: var(--bg-dark);
+  color: var(--text-main);
+  font-family: var(--font-mono);
+  line-height: 1.6;
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+/* Layout */
+.container {
+  max-width: 800px;
+  margin: 0 auto;
+  padding: 2rem 1rem;
+  width: 100%;
+  flex: 1;
+}
+
+/* Header & Footer */
+.simulator-header {
+  border-bottom: 2px solid var(--amber);
+  padding: 1rem;
+  text-align: center;
+  background-color: var(--bg-card);
+  box-shadow: 0 4px 12px var(--amber-dim);
+}
+
+.simulator-header h1 {
+  color: var(--amber);
+  font-size: 1.5rem;
+  text-transform: uppercase;
+  letter-spacing: 2px;
+  margin-bottom: 0.5rem;
+}
+
+.simulator-provider {
+  font-size: 0.9rem;
+  color: var(--text-muted);
+}
+
+.simulator-footer {
+  text-align: center;
+  padding: 1rem;
+  background-color: var(--neon-red-dim);
+  border-top: 1px solid var(--neon-red);
+  color: var(--neon-red);
+  font-weight: bold;
+  font-size: 0.9rem;
+  text-transform: uppercase;
+  letter-spacing: 1px;
+}
+
+/* Warning Badge */
+.sim-badge {
+  display: inline-block;
+  background-color: var(--amber);
+  color: var(--bg-dark);
+  padding: 0.25rem 0.5rem;
+  font-weight: bold;
+  border-radius: var(--border-radius);
+  text-transform: uppercase;
+  font-size: 0.8rem;
+}
+
+/* Typography elements */
+h2, h3 {
+  color: var(--text-main);
+  margin-bottom: 1rem;
+  font-weight: normal;
+  border-bottom: 1px dashed var(--text-muted);
+  padding-bottom: 0.5rem;
+}
+
+/* Card Component */
+.payment-card {
+  background-color: var(--bg-card);
+  border: 1px solid var(--text-muted);
+  border-left: 4px solid var(--amber);
+  border-radius: var(--border-radius);
+  padding: 1.5rem;
+  margin-bottom: 1.5rem;
+  transition: all 0.2s ease-in-out;
+}
+
+.payment-card:hover {
+  box-shadow: 0 0 15px var(--amber-dim);
+  border-color: var(--amber);
+}
+
+.payment-card-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 1rem;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.1);
+}
+
+.payment-amount {
+  font-size: 1.5rem;
+  color: var(--text-main);
+  font-weight: bold;
+}
+
+.payment-details {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 0.5rem 1rem;
+  font-size: 0.9rem;
+}
+
+.detail-label {
+  color: var(--text-muted);
+}
+
+.detail-value {
+  color: var(--text-main);
+}
+
+/* Status Badges */
+.status-badge {
+  display: inline-block;
+  padding: 0.25rem 0.75rem;
+  border-radius: 1rem;
+  font-size: 0.8rem;
+  font-weight: bold;
+  text-transform: uppercase;
+  letter-spacing: 1px;
+}
+
+.status-badge.status-pending {
+  background-color: var(--amber-dim);
+  color: var(--amber);
+  border: 1px solid var(--amber);
+  animation: pulse 2s infinite;
+}
+
+.status-badge.status-waiting_for_confirmation {
+  background-color: var(--amber-dim);
+  color: var(--amber);
+  border: 1px solid var(--amber);
+}
+
+.status-badge.status-completed {
+  background-color: var(--neon-green-dim);
+  color: var(--neon-green);
+  border: 1px solid var(--neon-green);
+  box-shadow: 0 0 8px var(--neon-green-dim);
+}
+
+.status-badge.status-canceled {
+  background-color: var(--neon-red-dim);
+  color: var(--neon-red);
+  border: 1px solid var(--neon-red);
+}
+
+/* Animations */
+@keyframes pulse {
+  0% { opacity: 0.8; box-shadow: 0 0 0 0 rgba(255, 153, 0, 0.4); }
+  50% { opacity: 1; box-shadow: 0 0 0 4px rgba(255, 153, 0, 0); }
+  100% { opacity: 0.8; box-shadow: 0 0 0 0 rgba(255, 153, 0, 0); }
+}
+
+/* Buttons */
+.btn {
+  display: inline-block;
+  padding: 0.75rem 1.5rem;
+  border: 1px solid var(--text-muted);
+  border-radius: var(--border-radius);
+  background-color: transparent;
+  color: var(--text-main);
+  font-family: inherit;
+  font-size: 1rem;
+  cursor: pointer;
+  text-decoration: none;
+  text-transform: uppercase;
+  transition: all 0.2s;
+  text-align: center;
+}
+
+.btn:hover {
+  background-color: rgba(255, 255, 255, 0.05);
+}
+
+.btn-approve {
+  border-color: var(--neon-green);
+  color: var(--neon-green);
+}
+
+.btn-approve:hover {
+  background-color: var(--neon-green-dim);
+  box-shadow: 0 0 10px var(--neon-green-dim);
+}
+
+.btn-reject {
+  border-color: var(--neon-red);
+  color: var(--neon-red);
+}
+
+.btn-reject:hover {
+  background-color: var(--neon-red-dim);
+  box-shadow: 0 0 10px var(--neon-red-dim);
+}
+
+.btn-neutral {
+  border-color: var(--amber);
+  color: var(--amber);
+}
+
+.btn-neutral:hover {
+  background-color: var(--amber-dim);
+  box-shadow: 0 0 10px var(--amber-dim);
+}
+
+.action-bar {
+  display: flex;
+  gap: 1rem;
+  margin-top: 1.5rem;
+  padding-top: 1rem;
+  border-top: 1px solid rgba(255, 255, 255, 0.1);
+}
+
+/* Responsive */
+@media (max-width: 480px) {
+  .simulator-header h1 {
+    font-size: 1.2rem;
+  }
+  
+  .action-bar {
+    flex-direction: column;
+  }
+  
+  .btn {
+    width: 100%;
+  }
+}

getpaid_simulator/ui/templates/authorize.html

@@ -0,0 +1,24 @@
+{% extends "base.html" %}
+
+{% block content %}
+<div class="authorization-container">
+    <div class="header">
+        <h1>Authorize Payment</h1>
+        <div class="provider-badge">{{ provider }}</div>
+    </div>
+    
+    {% include "components/payment_card.html" %}
+
+    <form method="POST" action="" class="action-buttons">
+        <button type="submit" name="action" value="approve" class="btn btn-approve">
+            <span class="btn-text">Approve Payment</span>
+            <div class="btn-glow"></div>
+        </button>
+        
+        <button type="submit" name="action" value="reject" class="btn btn-reject">
+            <span class="btn-text">Reject Payment</span>
+            <div class="btn-glow"></div>
+        </button>
+    </form>
+</div>
+{% endblock %}

getpaid_simulator/ui/templates/base.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="theme-color" content="#0d0d0d">
+    <meta name="color-scheme" content="dark">
+    <title>{% block title %}Simulator{% endblock %} | GetPaid Simulator</title>
+    <link rel="stylesheet" href="/static/style.css">
+</head>
+<body>
+    <header class="simulator-header">
+        <h1>⚡ GETPAID SIMULATOR</h1>
+        <div class="simulator-provider">
+            {% if provider %}
+                Simulating Provider: <strong>{{ provider }}</strong>
+            {% else %}
+                Test Environment
+            {% endif %}
+        </div>
+    </header>
+
+    <main class="container">
+        {% block content %}{% endblock %}
+    </main>
+
+    <footer class="simulator-footer">
+        SIMULATOR MODE — NOT A REAL PAYMENT GATEWAY
+    </footer>
+</body>
+</html>

getpaid_simulator/ui/templates/components/dashboard_payment_card.html

@@ -0,0 +1,9 @@
+{% extends "components/payment_card.html" %}
+
+{% block card_actions %}
+{% if authorize_url %}
+<a href="{{ authorize_url }}" class="btn btn-neutral">Authorize</a>
+{% else %}
+<span style="color: var(--text-muted);">No UI flow</span>
+{% endif %}
+{% endblock %}

getpaid_simulator/ui/templates/components/payment_card.html

@@ -0,0 +1,17 @@
+<div class="payment-card">
+    <div class="payment-card-header">
+        <div class="payment-amount">{{ amount }}</div>
+        {% include "components/status_badge.html" with context %}
+    </div>
+    <div class="payment-details">
+        <div class="detail-label">Order ID:</div>
+        <div class="detail-value">{{ order_id }}</div>
+        
+        <div class="detail-label">Provider:</div>
+        <div class="detail-value">{{ provider }}</div>
+    </div>
+    
+    <div class="action-bar">
+        {% block card_actions %}{% endblock %}
+    </div>
+</div>