Metadata-Version: 2.4
Name: commercexl
Version: 0.1.0
Summary: Composable commerce core for products, order items, and payments.
Author: xlartas
License-Expression: MIT
Project-URL: Homepage, https://github.com/Artasov/commercexl
Project-URL: Repository, https://github.com/Artasov/commercexl
Project-URL: Issues, https://github.com/Artasov/commercexl/issues
Keywords: commerce,fastapi,sqlalchemy,payments,orders,checkout
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Framework :: FastAPI
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: sqlalchemy>=2.0.0
Provides-Extra: test
Requires-Dist: aiosqlite>=0.20.0; extra == "test"
Requires-Dist: httpx>=0.28.0; extra == "test"
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=1.0.0; extra == "test"
Provides-Extra: dev
Requires-Dist: aiosqlite>=0.20.0; extra == "dev"
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: httpx>=0.28.0; extra == "dev"
Requires-Dist: mypy>=1.11.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.11.0; extra == "dev"
Requires-Dist: twine>=6.1.0; extra == "dev"
Dynamic: license-file

# commercexl

`commercexl` is a reusable commerce core for:

- product catalog records
- checkout orders
- order items
- payment systems
- FastAPI router assembly

It does not create your DB engine, session factory, auth, or project-specific payment callbacks.

## Installation

```bash
pip install commercexl
```

For tests and local development:

```bash
pip install "commercexl[test]"
pip install "commercexl[dev]"
```

## What the library gives you

- SQLAlchemy models via `CommerceBase`
- explicit module wiring via `CommerceModule`
- abstract services for products, order items, and payments
- built-in balance and handmade payments
- FastAPI router factory via `create_router(...)`

## Quick start

```python
from decimal import Decimal

from commercexl import (
    BaseConfig,
    CommerceModule,
    DefaultOrderItemService,
    HandMadePaymentService,
    PaymentConfigBuilder,
    ProductOrderConfig,
    ProductOrderConfigBuilder,
)


class ProjectCommerceConfig(BaseConfig):
    PAYMENT_SYSTEMS = {"USD": ("handmade",)}
    MIN_TOP_UP_AMOUNTS = {"USD": Decimal("1")}
    CREDITS_CONVERTERS = {"USD": Decimal("10000")}


commerce = CommerceModule(
    config_class=ProjectCommerceConfig,
    product_orders=ProductOrderConfigBuilder(
        ProductOrderConfig(MyProductService, DefaultOrderItemService),
    ),
    payments=PaymentConfigBuilder(HandMadePaymentService),
)
```

## FastAPI integration

```python
from commercexl import CommerceHTTPConfig, CommerceUserActorDTO, create_router

app.include_router(
    create_router(
        CommerceHTTPConfig(
            get_db_session_dependency=get_db_session,
            get_current_user_dependency=get_current_user,
            get_commerce_module=lambda: commerce,
            build_actor=lambda user: CommerceUserActorDTO(id=user.id),
            get_user_id=lambda user: int(user.id),
            is_staff=lambda user: bool(user.is_staff),
        ),
    ),
    prefix="/api/v1",
)
```

## Alembic

`commercexl` does not ship migrations. The host project owns migrations.

Add library metadata to your Alembic `target_metadata`:

```python
from commercexl import CommerceBase
from my_project.db import Base

target_metadata = [
    Base.metadata,
    CommerceBase.metadata,
]
```

## Docs

- [How to use](./src/commercexl/docs/HOW_TO_USE.md)
- [Promocodes](./src/commercexl/docs/PROMOCODES.md)

## Testing

```bash
pytest
```
