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
