# -*- coding: utf-8 -*-
# File generated from our OpenAPI spec
from stripe._createable_api_resource import CreateableAPIResource
from stripe._list_object import ListObject
from stripe._listable_api_resource import ListableAPIResource
from stripe._stripe_object import StripeObject
from typing import ClassVar, List, Optional, cast
from typing_extensions import Literal, Unpack, TYPE_CHECKING

if TYPE_CHECKING:
    from stripe._file import File
    from stripe.params.reporting._report_run_create_params import (
        ReportRunCreateParams,
    )
    from stripe.params.reporting._report_run_list_params import (
        ReportRunListParams,
    )
    from stripe.params.reporting._report_run_retrieve_params import (
        ReportRunRetrieveParams,
    )


class ReportRun(
    CreateableAPIResource["ReportRun"],
    ListableAPIResource["ReportRun"],
):
    """
    The Report Run object represents an instance of a report type generated with
    specific run parameters. Once the object is created, Stripe begins processing the report.
    When the report has finished running, it will give you a reference to a file
    where you can retrieve your results. For an overview, see
    [API Access to Reports](https://stripe.com/docs/reporting/statements/api).

    Note that certain report types can only be run based on your live-mode data (not test-mode
    data), and will error when queried without a [live-mode API key](https://stripe.com/docs/keys#test-live-modes).
    """

    OBJECT_NAME: ClassVar[Literal["reporting.report_run"]] = (
        "reporting.report_run"
    )

    class Parameters(StripeObject):
        columns: Optional[List[str]]
        """
        The set of output columns requested for inclusion in the report run.
        """
        connected_account: Optional[str]
        """
        Connected account ID by which to filter the report run.
        """
        currency: Optional[str]
        """
        Currency of objects to be included in the report run.
        """
        interval_end: Optional[int]
        """
        Ending timestamp of data to be included in the report run. Can be any UTC timestamp between 1 second after the user specified `interval_start` and 1 second before this report's last `data_available_end` value.
        """
        interval_start: Optional[int]
        """
        Starting timestamp of data to be included in the report run. Can be any UTC timestamp between 1 second after this report's `data_available_start` and 1 second before the user specified `interval_end` value.
        """
        payout: Optional[str]
        """
        Payout ID by which to filter the report run.
        """
        reporting_category: Optional[str]
        """
        Category of balance transactions to be included in the report run.
        """
        timezone: Optional[str]
        """
        Defaults to `Etc/UTC`. The output timezone for all timestamps in the report. A list of possible time zone values is maintained at the [IANA Time Zone Database](http://www.iana.org/time-zones). Has no effect on `interval_start` or `interval_end`.
        """

    created: int
    """
    Time at which the object was created. Measured in seconds since the Unix epoch.
    """
    error: Optional[str]
    """
    If something should go wrong during the run, a message about the failure (populated when
     `status=failed`).
    """
    id: str
    """
    Unique identifier for the object.
    """
    livemode: bool
    """
    `true` if the report is run on live mode data and `false` if it is run on test mode data.
    """
    object: Literal["reporting.report_run"]
    """
    String representing the object's type. Objects of the same type share the same value.
    """
    parameters: Parameters
    report_type: str
    """
    The ID of the [report type](https://stripe.com/docs/reports/report-types) to run, such as `"balance.summary.1"`.
    """
    result: Optional["File"]
    """
    The file object representing the result of the report run (populated when
     `status=succeeded`).
    """
    status: str
    """
    Status of this report run. This will be `pending` when the run is initially created.
     When the run finishes, this will be set to `succeeded` and the `result` field will be populated.
     Rarely, we may encounter an error, at which point this will be set to `failed` and the `error` field will be populated.
    """
    succeeded_at: Optional[int]
    """
    Timestamp at which this run successfully finished (populated when
     `status=succeeded`). Measured in seconds since the Unix epoch.
    """

    @classmethod
    def create(cls, **params: Unpack["ReportRunCreateParams"]) -> "ReportRun":
        """
        Creates a new object and begin running the report. (Certain report types require a [live-mode API key](https://stripe.com/docs/keys#test-live-modes).)
        """
        return cast(
            "ReportRun",
            cls._static_request(
                "post",
                cls.class_url(),
                params=params,
            ),
        )

    @classmethod
    async def create_async(
        cls, **params: Unpack["ReportRunCreateParams"]
    ) -> "ReportRun":
        """
        Creates a new object and begin running the report. (Certain report types require a [live-mode API key](https://stripe.com/docs/keys#test-live-modes).)
        """
        return cast(
            "ReportRun",
            await cls._static_request_async(
                "post",
                cls.class_url(),
                params=params,
            ),
        )

    @classmethod
    def list(
        cls, **params: Unpack["ReportRunListParams"]
    ) -> ListObject["ReportRun"]:
        """
        Returns a list of Report Runs, with the most recent appearing first.
        """
        result = cls._static_request(
            "get",
            cls.class_url(),
            params=params,
        )
        if not isinstance(result, ListObject):
            raise TypeError(
                "Expected list object from API, got %s"
                % (type(result).__name__)
            )

        return result

    @classmethod
    async def list_async(
        cls, **params: Unpack["ReportRunListParams"]
    ) -> ListObject["ReportRun"]:
        """
        Returns a list of Report Runs, with the most recent appearing first.
        """
        result = await cls._static_request_async(
            "get",
            cls.class_url(),
            params=params,
        )
        if not isinstance(result, ListObject):
            raise TypeError(
                "Expected list object from API, got %s"
                % (type(result).__name__)
            )

        return result

    @classmethod
    def retrieve(
        cls, id: str, **params: Unpack["ReportRunRetrieveParams"]
    ) -> "ReportRun":
        """
        Retrieves the details of an existing Report Run.
        """
        instance = cls(id, **params)
        instance.refresh()
        return instance

    @classmethod
    async def retrieve_async(
        cls, id: str, **params: Unpack["ReportRunRetrieveParams"]
    ) -> "ReportRun":
        """
        Retrieves the details of an existing Report Run.
        """
        instance = cls(id, **params)
        await instance.refresh_async()
        return instance

    _inner_class_types = {"parameters": Parameters}