python-getpaid-core 0.1.0__tar.gz → 3.0.0__tar.gz

python_getpaid_core-3.0.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint with ruff
+        run: uv run ruff check .
+
+      - name: Audit dependencies
+        run: uv run pip-audit --strict
+
+      - name: Run tests
+        run: uv run pytest --tb=short

python_getpaid_core-3.0.0/.github/workflows/release.yml

@@ -0,0 +1,70 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history needed for version detection
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: pip install uv
+
+      # Version is read from __init__.py (dynamic via hatch)
+      - name: Detect version from __init__.py
+        id: get-version
+        run: |
+          init_py=$(grep -A2 '\[tool\.hatch\.version\]' pyproject.toml | grep '^path\s*=' | head -1 | sed -E "s/path\s*=\s*['\"]([^'\"]+)['\"].*/\1/")
+          version=$(grep '__version__' "$init_py" | head -1 | sed -E "s/.*= ['\"]([^'\"]+)['\"].*/\1/")
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Check if tag already exists
+        id: check-tag
+        run: |
+          tag="v${{ steps.get-version.outputs.version }}"
+          if git rev-parse "$tag" >/dev/null 2>&1; then
+            echo "already_tagged=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "already_tagged=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Tag new version
+        if: steps.check-tag.outputs.already_tagged == 'false'
+        run: |
+          tag="v${{ steps.get-version.outputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "$tag" -m "Release $tag"
+          git push origin "$tag"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package on PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}
+
+      - name: Publish the release notes
+        if: steps.check-tag.outputs.already_tagged == 'false'
+        uses: release-drafter/release-drafter@v5.20.0
+        with:
+          publish: true
+          name: v${{ steps.get-version.outputs.version }}
+          tag: v${{ steps.get-version.outputs.version }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{python_getpaid_core-0.1.0 → python_getpaid_core-3.0.0}/.gitignore

@@ -6,6 +6,8 @@
 /.pytype/
 /dist/
 /docs/_build/
+/_build/
 /src/*.egg-info/
 __pycache__/
 /.idea/
+/uv.lock

python_getpaid_core-3.0.0/.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff
+        name: ruff
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+      - id: ruff-format
+        name: ruff-format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+      - id: check-toml
+        name: check-toml
+        entry: uv run check-toml
+        language: system
+        types: [toml]
+      - id: check-yaml
+        name: check-yaml
+        entry: uv run check-yaml
+        language: system
+        types: [yaml]
+      - id: end-of-file-fixer
+        name: end-of-file-fixer
+        entry: uv run end-of-file-fixer
+        language: system
+        types: [text]
+      - id: trailing-whitespace
+        name: trailing-whitespace
+        entry: uv run trailing-whitespace-fixer
+        language: system
+        types: [text]
+      - id: ty
+        name: ty
+        entry: uv run ty check
+        language: system
+        types: [python]
+        pass_filenames: false

python_getpaid_core-3.0.0/.sisyphus/evidence/task-22-readme-core.txt

@@ -0,0 +1,7 @@
+README.md verification results:
+Line count: 82
+pip install count: 1
+BaseProcessor count: 5
+Wrappers count: 8
+
+All verification checks PASSED.

python_getpaid_core-3.0.0/Makefile

@@ -0,0 +1,28 @@
+.PHONY: test test-bench lint type-check audit clean
+
+PYTHON ?= .venv/bin/python
+
+test:             ## Run all tests (unit + benchmarks)
+	$(PYTHON) -m pytest
+
+test-bench:       ## Run benchmarks only
+	$(PYTHON) -m pytest tests/test_benchmarks.py --benchmark-only --benchmark-min-rounds=10 --benchmark-sort=mean
+
+test-bench-save:  ## Run benchmarks and save results
+	$(PYTHON) -m pytest tests/test_benchmarks.py --benchmark-only --benchmark-autosave --benchmark-sort=mean
+
+test-bench-compare:  ## Compare current benchmarks against saved baseline
+	$(PYTHON) -m pytest tests/test_benchmarks.py --benchmark-only --benchmark-compare=0
+
+lint:             ## Run ruff linter
+	$(PYTHON) -m ruff check src tests
+
+type-check:       ## Run type checker
+	$(PYTHON) -m ty check src
+
+audit:            ## Audit dependencies for vulnerabilities
+	$(PYTHON) -m pip-audit
+
+clean:            ## Remove build artifacts and caches
+	rm -rf .pytest_cache .benchmarks .coverage htmlcov build dist *.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

python_getpaid_core-3.0.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: python-getpaid-core
+Version: 3.0.0
+Summary: Framework-agnostic payment processing core.
+Project-URL: Homepage, https://github.com/django-getpaid/python-getpaid-core
+Project-URL: Repository, https://github.com/django-getpaid/python-getpaid-core
+Project-URL: Documentation, https://getpaid-core.readthedocs.io
+Project-URL: Changelog, https://github.com/django-getpaid/python-getpaid-core/releases
+Author-email: Dominik Kozaczko <dominik@kozaczko.info>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+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
+Description-Content-Type: text/markdown
+
+# python-getpaid-core
+
+[![PyPI version](https://img.shields.io/pypi/v/python-getpaid-core)](https://pypi.org/project/python-getpaid-core/)
+[![Python version](https://img.shields.io/pypi/pyversions/python-getpaid-core)](https://pypi.org/project/python-getpaid-core/)
+[![License](https://img.shields.io/pypi/l/python-getpaid-core)](https://github.com/django-getpaid/python-getpaid-core/blob/main/LICENSE)
+
+**Framework-agnostic payment processing core.**
+
+`python-getpaid-core` is the foundation of the Getpaid ecosystem. It provides the abstract interfaces, semantic payment update engine, and plugin registry needed to build a robust payment system without coupling your logic to a specific web framework or payment provider.
+
+## Installation
+
+```bash
+pip install python-getpaid-core
+```
+
+## Quick Start: Creating a Custom Processor
+
+To implement a new payment backend, subclass `BaseProcessor` and implement at least `prepare_transaction`.
+
+```python
+from getpaid_core import BaseProcessor
+from getpaid_core.types import TransactionResult
+
+class MyPaymentProcessor(BaseProcessor):
+    slug = "my-provider"
+    display_name = "My Payment Provider"
+    accepted_currencies = ["USD", "EUR"]
+
+    async def prepare_transaction(self, **kwargs) -> TransactionResult:
+        # Generate payment link or form data
+        return TransactionResult(
+            redirect_url=f"https://api.provider.com/pay/{self.payment.id}",
+            method="GET"
+        )
+```
+
+### Registering your Processor
+
+Register your processor using entry points in your `pyproject.toml` so it can be discovered by the registry:
+
+```toml
+[project.entry-points."getpaid.backends"]
+my-provider = "my_package.processors:MyPaymentProcessor"
+```
+
+## Architecture Overview
+
+- **BaseProcessor**: The abstract base class that all payment gateway plugins must implement. It provides the standard interface for transaction preparation, callback handling, charging, and refunds.
+- **PaymentFlow**: Manages the payment lifecycle using semantic payment update objects. It ensures that payments move between states (e.g., `NEW` -> `PREPARED` -> `PAID`) according to strict business rules.
+- **PluginRegistry**: A central service for discovering and managing payment processors registered via `getpaid.backends` entry points.
+- **State Engine**: Applies semantic payment and fraud events to payment objects, merges provider metadata, and tracks idempotent provider event IDs.
+
+## API Summary
+
+| Class / Module | Role |
+| --- | --- |
+| `BaseProcessor` | Abstract base for implementing payment gateways. |
+| `PaymentFlow` | Semantic orchestration for payment lifecycles. |
+| `PaymentStatus` | Enum for all possible payment states (NEW, PAID, FAILED, etc.). |
+| `registry` | Singleton registry for backend discovery. |
+| `TransactionResult` | Standard response for transaction initiation. |
+| `GetPaidException` | Base exception for all payment-related errors. |
+
+## Ecosystem
+
+`getpaid-core` is the heart of a larger ecosystem designed to make payment processing easy in any Python web application.
+
+### Framework Wrappers
+- [django-getpaid](https://github.com/django-getpaid/django-getpaid) — Official Django integration.
+- [litestar-getpaid](https://github.com/django-getpaid/litestar-getpaid) — Official Litestar integration.
+- [fastapi-getpaid](https://github.com/django-getpaid/fastapi-getpaid) — Official FastAPI integration.
+
+### Processor Plugins
+- [python-getpaid-payu](https://github.com/django-getpaid/python-getpaid-payu) — PayU backend.
+- [python-getpaid-paynow](https://github.com/django-getpaid/python-getpaid-paynow) — Paynow backend.
+- [python-getpaid-bitpay](https://github.com/django-getpaid/python-getpaid-bitpay) — BitPay backend.
+- [python-getpaid-przelewy24](https://github.com/django-getpaid/python-getpaid-przelewy24) — Przelewy24 backend.
+
+## License
+
+This project is licensed under the MIT License.

python_getpaid_core-3.0.0/README.md

@@ -0,0 +1,82 @@
+# python-getpaid-core
+
+[![PyPI version](https://img.shields.io/pypi/v/python-getpaid-core)](https://pypi.org/project/python-getpaid-core/)
+[![Python version](https://img.shields.io/pypi/pyversions/python-getpaid-core)](https://pypi.org/project/python-getpaid-core/)
+[![License](https://img.shields.io/pypi/l/python-getpaid-core)](https://github.com/django-getpaid/python-getpaid-core/blob/main/LICENSE)
+
+**Framework-agnostic payment processing core.**
+
+`python-getpaid-core` is the foundation of the Getpaid ecosystem. It provides the abstract interfaces, semantic payment update engine, and plugin registry needed to build a robust payment system without coupling your logic to a specific web framework or payment provider.
+
+## Installation
+
+```bash
+pip install python-getpaid-core
+```
+
+## Quick Start: Creating a Custom Processor
+
+To implement a new payment backend, subclass `BaseProcessor` and implement at least `prepare_transaction`.
+
+```python
+from getpaid_core import BaseProcessor
+from getpaid_core.types import TransactionResult
+
+class MyPaymentProcessor(BaseProcessor):
+    slug = "my-provider"
+    display_name = "My Payment Provider"
+    accepted_currencies = ["USD", "EUR"]
+
+    async def prepare_transaction(self, **kwargs) -> TransactionResult:
+        # Generate payment link or form data
+        return TransactionResult(
+            redirect_url=f"https://api.provider.com/pay/{self.payment.id}",
+            method="GET"
+        )
+```
+
+### Registering your Processor
+
+Register your processor using entry points in your `pyproject.toml` so it can be discovered by the registry:
+
+```toml
+[project.entry-points."getpaid.backends"]
+my-provider = "my_package.processors:MyPaymentProcessor"
+```
+
+## Architecture Overview
+
+- **BaseProcessor**: The abstract base class that all payment gateway plugins must implement. It provides the standard interface for transaction preparation, callback handling, charging, and refunds.
+- **PaymentFlow**: Manages the payment lifecycle using semantic payment update objects. It ensures that payments move between states (e.g., `NEW` -> `PREPARED` -> `PAID`) according to strict business rules.
+- **PluginRegistry**: A central service for discovering and managing payment processors registered via `getpaid.backends` entry points.
+- **State Engine**: Applies semantic payment and fraud events to payment objects, merges provider metadata, and tracks idempotent provider event IDs.
+
+## API Summary
+
+| Class / Module | Role |
+| --- | --- |
+| `BaseProcessor` | Abstract base for implementing payment gateways. |
+| `PaymentFlow` | Semantic orchestration for payment lifecycles. |
+| `PaymentStatus` | Enum for all possible payment states (NEW, PAID, FAILED, etc.). |
+| `registry` | Singleton registry for backend discovery. |
+| `TransactionResult` | Standard response for transaction initiation. |
+| `GetPaidException` | Base exception for all payment-related errors. |
+
+## Ecosystem
+
+`getpaid-core` is the heart of a larger ecosystem designed to make payment processing easy in any Python web application.
+
+### Framework Wrappers
+- [django-getpaid](https://github.com/django-getpaid/django-getpaid) — Official Django integration.
+- [litestar-getpaid](https://github.com/django-getpaid/litestar-getpaid) — Official Litestar integration.
+- [fastapi-getpaid](https://github.com/django-getpaid/fastapi-getpaid) — Official FastAPI integration.
+
+### Processor Plugins
+- [python-getpaid-payu](https://github.com/django-getpaid/python-getpaid-payu) — PayU backend.
+- [python-getpaid-paynow](https://github.com/django-getpaid/python-getpaid-paynow) — Paynow backend.
+- [python-getpaid-bitpay](https://github.com/django-getpaid/python-getpaid-bitpay) — BitPay backend.
+- [python-getpaid-przelewy24](https://github.com/django-getpaid/python-getpaid-przelewy24) — Przelewy24 backend.
+
+## License
+
+This project is licensed under the MIT License.

python_getpaid_core-3.0.0/docs/changelog.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## v3.0.0 (2026-06-04)
+
+Major stable release — framework-agnostic payment processing core.
+
+### Breaking Changes
+
+- Complete rewrite as a framework-agnostic library, no longer coupled to Django
+- `django-fsm` dependency removed — replaced by runtime FSM via `transitions`
+- Requires Python 3.12+
+- `can_proceed()` replaced by `may_trigger()`
+
+### Features
+
+- Payment status enum (`PaymentStatus`) with 9 states matching django-getpaid v2 values
+- Fraud status enum (`FraudStatus`) with 4 states
+- Backend method and confirmation method enums
+- `BaseProcessor` abstract class for payment gateway plugins
+- Semantic payment and fraud update engine
+- Transition validation with `InvalidTransitionError`
+- Provider metadata merging and callback idempotency tracking
+- `PluginRegistry` with entry-point discovery and manual registration
+- Runtime-checkable protocols: `Payment`, `Order`, `PaymentRepository`
+- Dataclass response types: `BuyerInfo`, `ItemInfo`, `ChargeResult`,
+  `PaymentUpdate`, `RefundResult`, `TransactionResult`
+- Structured exception hierarchy with `context` support
+
+---
+
+## v0.1.0 (2026-02-13)
+
+Initial release — extracted from django-getpaid v2 and redesigned as a
+framework-agnostic library.
+
+### Features
+
+- Payment status enum (`PaymentStatus`) with 9 states matching django-getpaid v2
+  values for backward compatibility
+- Fraud status enum (`FraudStatus`) with 4 states
+- Backend method and confirmation method enums
+- `BaseProcessor` abstract class for payment gateway plugins
+- Semantic payment and fraud update engine
+- Transition validation with `InvalidTransitionError`
+- Provider metadata merging and callback idempotency tracking
+- `PluginRegistry` with entry-point discovery and manual registration
+- Runtime-checkable protocols: `Payment`, `Order`, `PaymentRepository`
+- Dataclass response types: `BuyerInfo`, `ItemInfo`, `ChargeResult`,
+  `PaymentUpdate`, `RefundResult`, `TransactionResult`
+- Structured exception hierarchy with `context` support

{python_getpaid_core-0.1.0 → python_getpaid_core-3.0.0}/docs/concepts.md

@@ -16,45 +16,35 @@ Payments move through these states:
 | `REFUND_STARTED` | `"refund_started"` | Refund initiated |
 | `REFUNDED` | `"refunded"` | Fully refunded or lock released |
 
-## Payment State Transitions
+## Payment Events
 
 ```
-NEW ──────────────────────► PREPARED
- │                             │
- │  confirm_lock               │ confirm_lock
- ▼                             ▼
-PRE_AUTH ◄─────────────────────┘
- │
- ├── confirm_charge_sent ──► IN_CHARGE
- │                             │
- │   confirm_payment           │ confirm_payment
- ▼                             ▼
-PARTIAL ◄──────────────────────┘
- │
- ├── mark_as_paid ──────────► PAID
- │
- ├── start_refund ──────────► REFUND_STARTED
- │                             │
- │   cancel_refund             │ confirm_refund
- ◄─────────────────────────────┘
- │
- └── mark_as_refunded ──────► REFUNDED
-
-NEW/PREPARED/PRE_AUTH ──fail──► FAILED
-PRE_AUTH ──release_lock──────► REFUNDED
+prepared         -> PREPARED
+locked           -> PRE_AUTH
+charge_requested -> IN_CHARGE
+payment_captured -> PARTIAL or PAID
+failed           -> FAILED
+refund_requested -> REFUND_STARTED
+refund_confirmed -> PARTIAL or REFUNDED
+refund_cancelled -> active paid status
+lock_released    -> REFUNDED
 ```
 
-### Transition Guards
+### Transition Rules
 
-Some transitions have guards that raise `MachineError` if conditions aren't met:
+The state engine raises `InvalidTransitionError` when an event is incompatible
+with the current payment state.
 
-- **`mark_as_paid`** requires `is_fully_paid()` — `amount_paid >= amount_required`
-- **`mark_as_refunded`** requires `is_fully_refunded()` — `amount_refunded >= amount_paid`
+- You cannot capture a payment after it is already refunded.
+- You cannot start a refund before the payment has been paid.
+- Refund confirmation moves to `REFUNDED` only when `amount_refunded >= amount_paid`.
 
-### Amount Callbacks
+### Amount Handling
 
-- **`confirm_lock`** stores the locked amount via `_store_locked_amount`
-- **`confirm_payment`** accumulates paid amount via `_accumulate_paid_amount`
+- `locked_amount` stores a pre-authorized amount.
+- `paid_amount` updates captured funds and may reduce `amount_locked`.
+- `refunded_amount` tracks refund progress.
+- `provider_data` stores provider-specific metadata such as refund IDs and applied callback IDs.
 
 ## Fraud Statuses
 
@@ -103,13 +93,14 @@ class Payment(Protocol):
     currency: str
     status: str
     backend: str
-    external_id: str
-    description: str
+    external_id: str | None
+    description: str | None
     amount_paid: Decimal
     amount_locked: Decimal
     amount_refunded: Decimal
     fraud_status: str
     fraud_message: str
+    provider_data: dict[str, Any]
 ```
 
 ### PaymentRepository Protocol
@@ -162,6 +153,7 @@ raise ChargeFailure("Gateway returned 500", context={"status_code": 500})
 |------|-------------|
 | `BuyerInfo` | TypedDict with `email`, `first_name`, `last_name`, `phone` (all optional) |
 | `ItemInfo` | TypedDict with `name`, `quantity`, `unit_price` |
-| `ChargeResponse` | TypedDict with `amount_charged`, `success`, `async_call` |
-| `PaymentStatusResponse` | TypedDict with `amount`, `status`, `external_id` (all optional) |
-| `TransactionResult` | TypedDict with `redirect_url`, `form_data`, `method`, `headers` |
+| `ChargeResult` | Dataclass with `amount_charged`, `success`, `async_call`, `provider_data` |
+| `PaymentUpdate` | Dataclass describing semantic payment/fraud events and amounts |
+| `RefundResult` | Dataclass with refund amount and provider metadata |
+| `TransactionResult` | Dataclass with redirect, method, external ID, and provider metadata |

{python_getpaid_core-0.1.0 → python_getpaid_core-3.0.0}/docs/conf.py

@@ -2,7 +2,7 @@
 
 project = "getpaid-core"
 author = "Dominik Kozaczko"
-copyright = "2022-2026, Dominik Kozaczko"
+project_copyright = "2022-2026, Dominik Kozaczko"
 
 extensions = [
     "sphinx.ext.autodoc",

{python_getpaid_core-0.1.0 → python_getpaid_core-3.0.0}/docs/getting-started.md

@@ -77,21 +77,30 @@ from getpaid_core.registry import registry
 registry.register(MyGatewayProcessor)
 ```
 
-## Payment State Machine
+## Payment Updates
 
-Payments move through states via an FSM powered by the `transitions` library.
-The machine attaches trigger methods directly to payment objects:
+Payments move through states by applying semantic `PaymentUpdate` objects.
+Processors return updates from callbacks and status polling, and the flow
+applies them to the payment object:
 
 ```python
-from getpaid_core.fsm import create_payment_machine
-
-machine = create_payment_machine(payment)
+from decimal import Decimal
 
-# Now payment has trigger methods:
-payment.confirm_prepared()   # NEW -> PREPARED
-payment.confirm_lock(amount=100)  # PREPARED -> PRE_AUTH
-payment.confirm_payment(amount=100)  # PRE_AUTH -> PARTIAL
-payment.mark_as_paid()       # PARTIAL -> PAID (if fully paid)
+from getpaid_core.fsm import apply_payment_update
+from getpaid_core.types import PaymentUpdate
+
+apply_payment_update(
+    payment,
+    PaymentUpdate(payment_event="prepared"),
+)
+
+apply_payment_update(
+    payment,
+    PaymentUpdate(
+        payment_event="payment_captured",
+        paid_amount=Decimal("100.00"),
+    ),
+)
 ```
 
-See {doc}`concepts` for the full state diagram and transition rules.
+See {doc}`concepts` for the lifecycle rules and semantic event mapping.

{python_getpaid_core-0.1.0 → python_getpaid_core-3.0.0}/docs/reference.md

@@ -16,7 +16,7 @@
    :undoc-members:
 ```
 
-## FSM
+## State Engine
 
 ```{eval-rst}
 .. automodule:: getpaid_core.fsm