"""
Provider-agnostic payout interface. Concrete mobile-money adapters (M-Pesa,
Tigo Pesa, Airtel Money) implement `initiate` and, for async gateways,
translate their callback into `parse_callback`.
"""
from __future__ import annotations

from dataclasses import dataclass
from decimal import Decimal


@dataclass
class PayoutResult:
    success: bool
    reference: str = ''
    message: str = ''
    # When a provider is asynchronous, `pending` means we await a callback.
    pending: bool = False


class PayoutProvider:
    name = 'base'

    def initiate(self, *, idempotency_key: str, amount: Decimal,
                 msisdn: str, account_name: str, provider: str) -> PayoutResult:
        """
        Start a disbursement. MUST be idempotent on `idempotency_key`: calling
        twice with the same key must not move money twice.
        """
        raise NotImplementedError

    def parse_callback(self, payload: dict) -> tuple[str, PayoutResult]:
        """Map an async provider callback to (idempotency_key, PayoutResult)."""
        raise NotImplementedError