python-getpaid-simulator 3.0.0a3__tar.gz

python_getpaid_simulator-3.0.0a3/.gitignore

@@ -0,0 +1,77 @@
+*.py[cod]
+__pycache__
+
+# C extensions
+*.so
+
+# Packages
+*.egg
+*.egg-info
+dist
+build
+eggs
+parts
+bin
+var
+sdist
+develop-eggs
+.installed.cfg
+lib
+lib64
+
+# Installer logs
+pip-log.txt
+
+# Unit test / coverage reports
+.coverage
+coverage.xml
+.tox
+nosetests.xml
+htmlcov
+
+# Translations
+*.mo
+
+# Mr Developer
+.mr.developer.cfg
+.project
+.pydevproject
+
+# Pycharm/Intellij
+.idea
+
+# Complexity
+output/*.html
+output/*/index.html
+
+# Sphinx
+docs/_build
+
+# Default Django Database
+db.sqlite3
+
+# pipenv
+/Pipfile
+/Pipfile.lock
+
+# pyenv
+.python-version
+
+# virtualenv
+venv
+.venv
+virtualenv
+.virtualenv
+
+# poetry
+/poetry.lock
+
+# Codacy
+/.codacy-coverage
+/codacy-coverage.json
+
+# Sublime text (editor)
+*.sublime-project
+*.sublime-workspace
+.sisyphus
+uv.lock

python_getpaid_simulator-3.0.0a3/Dockerfile

@@ -0,0 +1,29 @@
+FROM python:3.12-slim
+
+# Install uv
+RUN pip install --no-cache-dir uv
+
+# Create non-root user
+RUN useradd -m -u 1000 simulator
+
+# Copy all sibling packages (build context is parent directory)
+COPY getpaid-core/ /app/getpaid-core/
+COPY getpaid-payu/ /app/getpaid-payu/
+COPY getpaid-paynow/ /app/getpaid-paynow/
+COPY getpaid-simulator/ /app/getpaid-simulator/
+
+# Set working directory
+WORKDIR /app/getpaid-simulator
+
+# Install dependencies (no dev tools, include e2e group for PayU/PayNow)
+RUN uv sync --group e2e --no-dev
+
+# Switch to non-root user (AFTER all RUN/COPY)
+USER simulator
+
+# Expose port
+EXPOSE 9000
+
+# Run simulator with virtual environment
+ENV PATH="/app/getpaid-simulator/.venv/bin:$PATH"
+CMD ["python", "-m", "getpaid_simulator"]

python_getpaid_simulator-3.0.0a3/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: python-getpaid-simulator
+Version: 3.0.0a3
+Summary: Payment gateway simulator for testing the python-getpaid ecosystem.
+Project-URL: Homepage, https://github.com/django-getpaid/python-getpaid-simulator
+Project-URL: Repository, https://github.com/django-getpaid/python-getpaid-simulator
+Author-email: Dominik Kozaczko <dominik@kozaczko.info>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jinja2>=3.0
+Requires-Dist: litestar>=2.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Description-Content-Type: text/markdown
+
+# python-getpaid-simulator
+
+Payment gateway simulator host for testing the python-getpaid ecosystem.
+
+The simulator no longer owns provider implementations directly. It starts a
+generic Litestar host, discovers provider plugins from installed packages, and
+mounts each provider's API routes and UI flows through entry points.
+
+## Installation
+
+```bash
+pip install python-getpaid-simulator
+```
+
+The host only becomes useful when at least one provider package exposing the
+simulator plugin entry point is installed in the same environment.
+
+## Plugin Model
+
+Provider packages must expose an entry point in the
+`getpaid.simulator.providers` group.
+
+Example from a provider package:
+
+```toml
+[project.entry-points."getpaid.simulator.providers"]
+payu = "getpaid_payu.simulator:get_plugin"
+```
+
+The entry point must resolve to a factory returning a
+`getpaid_simulator.spi.SimulatorProviderPlugin`.
+
+The current stable plugin contract requires:
+
+- `api_version`
+- `slug`
+- `display_name`
+- `api_handlers`
+- `ui_handlers`
+- `transitions`
+- `load_config(env)`
+- optional `authorize_path_template`
+
+The host validates the plugin slug against the entry point name and rejects
+plugins that do not match `getpaid_simulator.spi.SIMULATOR_PLUGIN_API_VERSION`.
+
+## Startup Failure Modes
+
+Plugin loading is controlled by `SIMULATOR_PLUGIN_FAILURE_MODE` or the CLI flag
+`--plugin-failure-mode`.
+
+- `warn` (default): broken plugins are skipped, the simulator starts in
+  degraded mode, and failed providers appear in logs, `/`, `/sim/status`, and
+  the dashboard.
+- `strict`: the first plugin import, factory, compatibility, or config failure
+  aborts startup with `PluginLoadError`.
+
+Examples:
+
+```bash
+getpaid-simulator --plugin-failure-mode strict
+SIMULATOR_PLUGIN_FAILURE_MODE=warn getpaid-simulator
+```
+
+## Provider Packaging
+
+Provider packages should keep simulator support in an optional dependency group
+such as `simulator`, rather than forcing simulator host and Litestar
+dependencies into normal runtime installs.
+
+Example:
+
+```toml
+[project.optional-dependencies]
+simulator = [
+    "python-getpaid-simulator>=3.0.0a3",
+    "litestar>=2.0",
+]
+```
+
+## Development Notes
+
+- Wave 1 storage remains in-memory behind the host storage interface.
+- Provider-local simulator code lives in provider repositories, not under
+  `getpaid_simulator.providers`.
+
+## License
+
+MIT

python_getpaid_simulator-3.0.0a3/README.md

@@ -0,0 +1,89 @@
+# python-getpaid-simulator
+
+Payment gateway simulator host for testing the python-getpaid ecosystem.
+
+The simulator no longer owns provider implementations directly. It starts a
+generic Litestar host, discovers provider plugins from installed packages, and
+mounts each provider's API routes and UI flows through entry points.
+
+## Installation
+
+```bash
+pip install python-getpaid-simulator
+```
+
+The host only becomes useful when at least one provider package exposing the
+simulator plugin entry point is installed in the same environment.
+
+## Plugin Model
+
+Provider packages must expose an entry point in the
+`getpaid.simulator.providers` group.
+
+Example from a provider package:
+
+```toml
+[project.entry-points."getpaid.simulator.providers"]
+payu = "getpaid_payu.simulator:get_plugin"
+```
+
+The entry point must resolve to a factory returning a
+`getpaid_simulator.spi.SimulatorProviderPlugin`.
+
+The current stable plugin contract requires:
+
+- `api_version`
+- `slug`
+- `display_name`
+- `api_handlers`
+- `ui_handlers`
+- `transitions`
+- `load_config(env)`
+- optional `authorize_path_template`
+
+The host validates the plugin slug against the entry point name and rejects
+plugins that do not match `getpaid_simulator.spi.SIMULATOR_PLUGIN_API_VERSION`.
+
+## Startup Failure Modes
+
+Plugin loading is controlled by `SIMULATOR_PLUGIN_FAILURE_MODE` or the CLI flag
+`--plugin-failure-mode`.
+
+- `warn` (default): broken plugins are skipped, the simulator starts in
+  degraded mode, and failed providers appear in logs, `/`, `/sim/status`, and
+  the dashboard.
+- `strict`: the first plugin import, factory, compatibility, or config failure
+  aborts startup with `PluginLoadError`.
+
+Examples:
+
+```bash
+getpaid-simulator --plugin-failure-mode strict
+SIMULATOR_PLUGIN_FAILURE_MODE=warn getpaid-simulator
+```
+
+## Provider Packaging
+
+Provider packages should keep simulator support in an optional dependency group
+such as `simulator`, rather than forcing simulator host and Litestar
+dependencies into normal runtime installs.
+
+Example:
+
+```toml
+[project.optional-dependencies]
+simulator = [
+    "python-getpaid-simulator>=3.0.0a3",
+    "litestar>=2.0",
+]
+```
+
+## Development Notes
+
+- Wave 1 storage remains in-memory behind the host storage interface.
+- Provider-local simulator code lives in provider repositories, not under
+  `getpaid_simulator.providers`.
+
+## License
+
+MIT

python_getpaid_simulator-3.0.0a3/docker-compose.yml

@@ -0,0 +1,18 @@
+version: "3.9"
+
+services:
+  simulator:
+    build:
+      context: ..
+      dockerfile: getpaid-simulator/Dockerfile
+    ports:
+      - "9000:9000"
+    environment:
+      - SIMULATOR_HOST=0.0.0.0
+      - SIMULATOR_PORT=9000
+      - SIMULATOR_LOG_LEVEL=info
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9000/sim/dashboard"]
+      interval: 10s
+      timeout: 5s
+      retries: 3

python_getpaid_simulator-3.0.0a3/pyproject.toml

@@ -0,0 +1,125 @@
+[project]
+name = 'python-getpaid-simulator'
+dynamic = ["version"]
+description = 'Payment gateway simulator for testing the python-getpaid ecosystem.'
+readme = 'README.md'
+license = {text = 'MIT'}
+authors = [
+    {name = 'Dominik Kozaczko', email = 'dominik@kozaczko.info'},
+]
+requires-python = '>=3.12'
+classifiers = [
+    'Development Status :: 3 - Alpha',
+    'Intended Audience :: Developers',
+    'License :: OSI Approved :: MIT License',
+    'Programming Language :: Python :: 3.12',
+    'Programming Language :: Python :: 3.13',
+    'Topic :: Office/Business :: Financial',
+    'Topic :: Office/Business :: Financial :: Point-Of-Sale',
+    'Typing :: Typed',
+]
+dependencies = [
+    'litestar>=2.0',
+    'jinja2>=3.0',
+    'httpx>=0.27.0',
+    'uvicorn[standard]>=0.30.0',
+]
+
+[dependency-groups]
+dev = [
+    'pytest>=8.0',
+    'pytest-asyncio>=0.24.0',
+    'pytest-cov>=5.0',
+    'ruff>=0.9.0',
+    'pre-commit>=4.0',
+    'ty>=0.0.16',
+    'litestar[testing]',
+    'respx>=0.21.0',
+    "playwright>=1.40.0",
+    'python-getpaid-payu>=3.0.0a3',
+    'python-getpaid-paynow>=3.0.0a3',
+]
+e2e = [
+    {include-group = "dev"},
+    'python-getpaid-core>=3.0.0a3',
+    'python-getpaid-payu',
+    'python-getpaid-paynow',
+]
+
+[project.scripts]
+getpaid-simulator = "getpaid_simulator.__main__:main"
+
+[project.urls]
+Homepage = 'https://github.com/django-getpaid/python-getpaid-simulator'
+Repository = 'https://github.com/django-getpaid/python-getpaid-simulator'
+
+[build-system]
+requires = ['hatchling']
+build-backend = 'hatchling.build'
+
+[tool.hatch.build.targets.wheel]
+packages = ['src/getpaid_simulator']
+
+[tool.hatch.version]
+path = "src/getpaid_simulator/__init__.py"
+
+[tool.uv.sources]
+python-getpaid-core = { path = "../getpaid-core", editable = true }
+python-getpaid-payu = { path = "../getpaid-payu", editable = true }
+python-getpaid-paynow = { path = "../getpaid-paynow", editable = true }
+
+[tool.pytest.ini_options]
+testpaths = ['tests']
+asyncio_mode = 'auto'
+
+[tool.coverage.run]
+branch = true
+source = ['getpaid_simulator']
+
+[tool.coverage.report]
+show_missing = true
+
+[tool.ruff]
+target-version = 'py312'
+line-length = 80
+src = ['src', 'tests']
+
+[tool.ruff.lint]
+select = [
+    'E',    # pycodestyle errors
+    'W',    # pycodestyle warnings
+    'F',    # pyflakes
+    'I',    # isort
+    'N',    # pep8-naming
+    'UP',   # pyupgrade
+    'B',    # flake8-bugbear
+    'A',    # flake8-builtins
+    'SIM',  # flake8-simplify
+    'TC',   # type-checking imports
+    'RUF',  # ruff-specific
+]
+ignore = [
+    'N818',  # Exception names match getpaid-core convention
+    'B027',  # Empty methods in ABC are intentional default no-ops
+]
+
+[tool.ruff.lint.per-file-ignores]
+'tests/**' = ['TC001', 'RUF012']
+
+[tool.ruff.lint.isort]
+force-single-line = true
+lines-after-imports = 2
+known-first-party = ['getpaid_simulator']
+
+# --- ty type checker ---
+[tool.ty.environment]
+python-version = '3.12'
+
+[tool.ty.terminal]
+error-on-warning = true
+
+[[tool.ty.overrides]]
+include = ['tests/**']
+[tool.ty.overrides.rules]
+unresolved-attribute = 'ignore'
+invalid-argument-type = 'ignore'

python_getpaid_simulator-3.0.0a3/src/getpaid_simulator/__init__.py

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

python_getpaid_simulator-3.0.0a3/src/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()

python_getpaid_simulator-3.0.0a3/src/getpaid_simulator/app.py

@@ -0,0 +1,130 @@
+"""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.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,
+        }
+    )
+
+    return Litestar(
+        route_handlers=route_handlers,
+        state=state,
+        template_config=TemplateConfig(
+            engine=JinjaTemplateEngine(
+                directory=Path(__file__).parent / "ui" / "templates"
+            )
+        ),
+    )
+
+
+app = create_app()

python_getpaid_simulator-3.0.0a3/src/getpaid_simulator/core/__init__.py

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