"""Invoice resource for the MercadoPago Subscriptions API.

Wraps ``/authorized_payments`` endpoints to retrieve and search invoices
generated by subscription (pre-approval) billing cycles.  Each invoice
represents a scheduled charge attempt against the subscriber's payment
method.

`API reference
<https://www.mercadopago.com/developers/en/reference/online-payments/subscriptions/get-authorized-payment/get>`_
"""
from mercadopago.core import MPBase


class Invoice(MPBase):
    """Provides read access to subscription invoices (authorized payments).

    Each invoice corresponds to a billing cycle of a
    :class:`~mercadopago.resources.preapproval.PreApproval` and tracks
    the charge amount, status, retry attempts, and the resulting
    payment.  Use :meth:`get` and :meth:`search` to monitor billing
    cycles and their outcomes.
    """

    def get(self, invoice_id, request_options=None):
        """Retrieves a single invoice (authorized payment) by its ID.

        Args:
            invoice_id: Unique invoice identifier assigned by
                MercadoPago.
            request_options: Per-call configuration overrides.

        Returns:
            dict: Full invoice object including ``status``,
                ``transaction_amount``, ``preapproval_id``, and
                associated ``payment`` details.

        Reference: https://www.mercadopago.com/developers/en/reference/online-payments/subscriptions/get-authorized-payment/get
        """
        return self._get(
            uri="/authorized_payments/" + self._path_param(invoice_id),
            request_options=request_options,
        )

    def search(self, filters=None, request_options=None):
        """Searches invoices matching the given filters.

        Args:
            filters: Query-string parameters such as ``preapproval_id``,
                ``status``, ``payer_id``, ``offset``, and ``limit``.
            request_options: Per-call configuration overrides.

        Returns:
            dict: Paginated result with ``paging`` metadata and a
                ``results`` list of matching invoices.

        Reference: https://www.mercadopago.com/developers/en/reference/online-payments/subscriptions/authorized-payment-search/get
        """
        return self._get(
            uri="/authorized_payments/search",
            filters=filters,
            request_options=request_options,
        )
