"""
Payment provider factory.

Usage
-----
    from src.core.payment_provider import get_provider_client

    client = get_provider_client()
    charge = await client.submit_charge(...)

When the environment variable PAYMENT_PROVIDER_STUB=true the factory
returns a `StubProviderClient` that completes all operations in-memory
without making any network calls.  All other values (including the
default of false / missing) return the real `PayrixProviderClient`.

The stub is completely invisible in production: the factory reads
`settings.PAYMENT_PROVIDER_STUB` which defaults to False, so no
behaviour changes unless the flag is explicitly set.
"""
from __future__ import annotations

from typing import TYPE_CHECKING, Optional

if TYPE_CHECKING:
    from sqlalchemy.orm import Session

from src.core.payment_provider.base import PaymentProviderClient


def get_provider_client(session: Optional["Session"] = None) -> PaymentProviderClient:
    """
    Return a payment provider client appropriate for the current environment.

    Args:
        session: Optional SQLAlchemy session.  Required only when calling
                 `get_token_details()` via the Payrix real client.

    Returns:
        StubProviderClient  — when PAYMENT_PROVIDER_STUB=true
        PayrixProviderClient — otherwise (production default)
    """
    from src.core.config import settings

    if settings.PAYMENT_PROVIDER_STUB:
        from src.core.payment_provider.stub import StubProviderClient
        return StubProviderClient()

    from src.core.payment_provider.payrix import PayrixProviderClient
    return PayrixProviderClient(session=session)