# This file was auto-generated by Fern from our API Definition.

import typing

from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
from ..core.request_options import RequestOptions
from ..types.countries import Countries
from ..types.from_rank import FromRank
from ..types.include_additional_info import IncludeAdditionalInfo
from ..types.is_news_domain import IsNewsDomain
from ..types.lang import Lang
from ..types.news_domain_type import NewsDomainType
from ..types.news_type import NewsType
from ..types.predefined_sources import PredefinedSources
from ..types.source_name import SourceName
from ..types.source_url import SourceUrl
from ..types.sources_response_dto import SourcesResponseDto
from ..types.to_rank import ToRank
from .raw_client import AsyncRawSourcesClient, RawSourcesClient
from .types.sources_get_request_news_domain_type import SourcesGetRequestNewsDomainType

# this is used as the default value for optional parameters
OMIT = typing.cast(typing.Any, ...)


class SourcesClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawSourcesClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> RawSourcesClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        RawSourcesClient
        """
        return self._raw_client

    def get(
        self,
        *,
        lang: typing.Optional[str] = None,
        countries: typing.Optional[str] = None,
        predefined_sources: typing.Optional[str] = None,
        source_name: typing.Optional[str] = None,
        source_url: typing.Optional[str] = None,
        include_additional_info: typing.Optional[bool] = None,
        is_news_domain: typing.Optional[bool] = None,
        news_domain_type: typing.Optional[SourcesGetRequestNewsDomainType] = None,
        news_type: typing.Optional[str] = None,
        from_rank: typing.Optional[int] = None,
        to_rank: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SourcesResponseDto:
        """
        Retrieves a list of sources based on specified criteria such as language, country, rank, and more.

        Parameters
        ----------
        lang : typing.Optional[str]
            The language(s) of the search. The only accepted format is the two-letter [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) code. To select multiple languages, use a comma-separated string.

            Example: `"en, es"`

            To learn more, see [Enumerated parameters > Language](/docs/v3/api-reference/overview/enumerated-parameters#language-lang-and-not-lang).

        countries : typing.Optional[str]
            The countries where the news publisher is located. The accepted format is the two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code. To select multiple countries, use a comma-separated string.

            Example: `"US, CA"`

            To learn more, see [Enumerated parameters > Country](/docs/v3/api-reference/overview/enumerated-parameters#country-country-and-not-country).

        predefined_sources : typing.Optional[str]
            Predefined top news sources per country.

            Format: start with the word `top`, followed by the number of desired sources, and then the two-letter country code [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Multiple countries with the number of top sources can be specified as a comma-separated string.

            Examples:
            - `"top 100 US"`
            - `"top 33 AT"`
            - `"top 50 US, top 20 GB"`
            - `"top 33 AT, top 50 IT"`

        source_name : typing.Optional[str]
            Word or phrase to search within the source names. To specify multiple values, use a comma-separated string.

            Example: `"sport, tech"`

            **Note**: The search doesn't require an exact match and returns sources containing the specified terms in their names. You can use any word or phrase, like `"sport"` or `"new york times"`. For example, `"sport"` returns sources such as `"Motorsport"`, `"Dot Esport"`, and `"Tuttosport"`.

        source_url : typing.Optional[str]
            The domain(s) of the news publication to search for.

            **Caution**:  When specifying the `source_url` parameter,
            you can only use `include_additional_info` as an extra parameter.

        include_additional_info : typing.Optional[bool]
            If true, returns the following additional datapoints about each news source:
            - `nb_articles_for_7d`: The number of articles published by the source in the last week.
            - `country`: Source country of origin.
            - `rank`: SEO rank.
            - `is_news_domain`: Boolean indicating if the source is a news domain.
            - `news_domain_type`: Type of news domain (e.g., "Original Content").
            - `news_type`: Category of news (e.g., "General News Outlets").

        is_news_domain : typing.Optional[bool]
            If true, filters results to include only news domains.

        news_domain_type : typing.Optional[SourcesGetRequestNewsDomainType]
            Filters results based on the news domain type. Possible values are:
            - `Original Content`: Sources that produce their own content.
            - `Aggregator`: Sources that collect content from various other sources.
            - `Press Releases`: Sources primarily publishing press releases.
            - `Republisher`: Sources that republish content from other sources.
            - `Other`: Sources that don't fit into main categories.

        news_type : typing.Optional[str]
            Filters results based on the news type. Multiple types can be specified using a comma-separated string.

            Example: `"General News Outlets,Tech News and Updates"`

            For a complete list of available news types, see [Enumerated parameters > News type](/docs/v3/api-reference/overview/enumerated-parameters#news-type-news-type).

        from_rank : typing.Optional[int]
            The lowest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source.

        to_rank : typing.Optional[int]
            The highest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SourcesResponseDto
            A successful response containing a list of news sources that match the specified criteria.

        Examples
        --------
        from newscatcher import NewscatcherApi

        client = NewscatcherApi(
            api_key="YOUR_API_KEY",
        )
        client.sources.get(
            predefined_sources="top 100 US, top 5 GB",
            source_url="bbc.com",
        )
        """
        _response = self._raw_client.get(
            lang=lang,
            countries=countries,
            predefined_sources=predefined_sources,
            source_name=source_name,
            source_url=source_url,
            include_additional_info=include_additional_info,
            is_news_domain=is_news_domain,
            news_domain_type=news_domain_type,
            news_type=news_type,
            from_rank=from_rank,
            to_rank=to_rank,
            request_options=request_options,
        )
        return _response.data

    def post(
        self,
        *,
        lang: typing.Optional[Lang] = OMIT,
        countries: typing.Optional[Countries] = OMIT,
        predefined_sources: typing.Optional[PredefinedSources] = OMIT,
        source_name: typing.Optional[SourceName] = OMIT,
        source_url: typing.Optional[SourceUrl] = OMIT,
        include_additional_info: typing.Optional[IncludeAdditionalInfo] = OMIT,
        is_news_domain: typing.Optional[IsNewsDomain] = OMIT,
        news_domain_type: typing.Optional[NewsDomainType] = OMIT,
        news_type: typing.Optional[NewsType] = OMIT,
        from_rank: typing.Optional[FromRank] = OMIT,
        to_rank: typing.Optional[ToRank] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SourcesResponseDto:
        """
        Retrieves the list of sources available in the database. You can filter the sources by language, country, and more.

        Parameters
        ----------
        lang : typing.Optional[Lang]

        countries : typing.Optional[Countries]

        predefined_sources : typing.Optional[PredefinedSources]

        source_name : typing.Optional[SourceName]

        source_url : typing.Optional[SourceUrl]

        include_additional_info : typing.Optional[IncludeAdditionalInfo]

        is_news_domain : typing.Optional[IsNewsDomain]

        news_domain_type : typing.Optional[NewsDomainType]

        news_type : typing.Optional[NewsType]

        from_rank : typing.Optional[FromRank]

        to_rank : typing.Optional[ToRank]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SourcesResponseDto
            A successful response containing a list of news sources that match the specified criteria.

        Examples
        --------
        from newscatcher import NewscatcherApi

        client = NewscatcherApi(
            api_key="YOUR_API_KEY",
        )
        client.sources.post(
            predefined_sources=["top 50 US"],
            include_additional_info=True,
            is_news_domain=True,
            news_domain_type="Original Content",
            news_type="General News Outlets",
        )
        """
        _response = self._raw_client.post(
            lang=lang,
            countries=countries,
            predefined_sources=predefined_sources,
            source_name=source_name,
            source_url=source_url,
            include_additional_info=include_additional_info,
            is_news_domain=is_news_domain,
            news_domain_type=news_domain_type,
            news_type=news_type,
            from_rank=from_rank,
            to_rank=to_rank,
            request_options=request_options,
        )
        return _response.data


class AsyncSourcesClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawSourcesClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> AsyncRawSourcesClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        AsyncRawSourcesClient
        """
        return self._raw_client

    async def get(
        self,
        *,
        lang: typing.Optional[str] = None,
        countries: typing.Optional[str] = None,
        predefined_sources: typing.Optional[str] = None,
        source_name: typing.Optional[str] = None,
        source_url: typing.Optional[str] = None,
        include_additional_info: typing.Optional[bool] = None,
        is_news_domain: typing.Optional[bool] = None,
        news_domain_type: typing.Optional[SourcesGetRequestNewsDomainType] = None,
        news_type: typing.Optional[str] = None,
        from_rank: typing.Optional[int] = None,
        to_rank: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SourcesResponseDto:
        """
        Retrieves a list of sources based on specified criteria such as language, country, rank, and more.

        Parameters
        ----------
        lang : typing.Optional[str]
            The language(s) of the search. The only accepted format is the two-letter [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) code. To select multiple languages, use a comma-separated string.

            Example: `"en, es"`

            To learn more, see [Enumerated parameters > Language](/docs/v3/api-reference/overview/enumerated-parameters#language-lang-and-not-lang).

        countries : typing.Optional[str]
            The countries where the news publisher is located. The accepted format is the two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code. To select multiple countries, use a comma-separated string.

            Example: `"US, CA"`

            To learn more, see [Enumerated parameters > Country](/docs/v3/api-reference/overview/enumerated-parameters#country-country-and-not-country).

        predefined_sources : typing.Optional[str]
            Predefined top news sources per country.

            Format: start with the word `top`, followed by the number of desired sources, and then the two-letter country code [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Multiple countries with the number of top sources can be specified as a comma-separated string.

            Examples:
            - `"top 100 US"`
            - `"top 33 AT"`
            - `"top 50 US, top 20 GB"`
            - `"top 33 AT, top 50 IT"`

        source_name : typing.Optional[str]
            Word or phrase to search within the source names. To specify multiple values, use a comma-separated string.

            Example: `"sport, tech"`

            **Note**: The search doesn't require an exact match and returns sources containing the specified terms in their names. You can use any word or phrase, like `"sport"` or `"new york times"`. For example, `"sport"` returns sources such as `"Motorsport"`, `"Dot Esport"`, and `"Tuttosport"`.

        source_url : typing.Optional[str]
            The domain(s) of the news publication to search for.

            **Caution**:  When specifying the `source_url` parameter,
            you can only use `include_additional_info` as an extra parameter.

        include_additional_info : typing.Optional[bool]
            If true, returns the following additional datapoints about each news source:
            - `nb_articles_for_7d`: The number of articles published by the source in the last week.
            - `country`: Source country of origin.
            - `rank`: SEO rank.
            - `is_news_domain`: Boolean indicating if the source is a news domain.
            - `news_domain_type`: Type of news domain (e.g., "Original Content").
            - `news_type`: Category of news (e.g., "General News Outlets").

        is_news_domain : typing.Optional[bool]
            If true, filters results to include only news domains.

        news_domain_type : typing.Optional[SourcesGetRequestNewsDomainType]
            Filters results based on the news domain type. Possible values are:
            - `Original Content`: Sources that produce their own content.
            - `Aggregator`: Sources that collect content from various other sources.
            - `Press Releases`: Sources primarily publishing press releases.
            - `Republisher`: Sources that republish content from other sources.
            - `Other`: Sources that don't fit into main categories.

        news_type : typing.Optional[str]
            Filters results based on the news type. Multiple types can be specified using a comma-separated string.

            Example: `"General News Outlets,Tech News and Updates"`

            For a complete list of available news types, see [Enumerated parameters > News type](/docs/v3/api-reference/overview/enumerated-parameters#news-type-news-type).

        from_rank : typing.Optional[int]
            The lowest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source.

        to_rank : typing.Optional[int]
            The highest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SourcesResponseDto
            A successful response containing a list of news sources that match the specified criteria.

        Examples
        --------
        import asyncio

        from newscatcher import AsyncNewscatcherApi

        client = AsyncNewscatcherApi(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.sources.get(
                predefined_sources="top 100 US, top 5 GB",
                source_url="bbc.com",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get(
            lang=lang,
            countries=countries,
            predefined_sources=predefined_sources,
            source_name=source_name,
            source_url=source_url,
            include_additional_info=include_additional_info,
            is_news_domain=is_news_domain,
            news_domain_type=news_domain_type,
            news_type=news_type,
            from_rank=from_rank,
            to_rank=to_rank,
            request_options=request_options,
        )
        return _response.data

    async def post(
        self,
        *,
        lang: typing.Optional[Lang] = OMIT,
        countries: typing.Optional[Countries] = OMIT,
        predefined_sources: typing.Optional[PredefinedSources] = OMIT,
        source_name: typing.Optional[SourceName] = OMIT,
        source_url: typing.Optional[SourceUrl] = OMIT,
        include_additional_info: typing.Optional[IncludeAdditionalInfo] = OMIT,
        is_news_domain: typing.Optional[IsNewsDomain] = OMIT,
        news_domain_type: typing.Optional[NewsDomainType] = OMIT,
        news_type: typing.Optional[NewsType] = OMIT,
        from_rank: typing.Optional[FromRank] = OMIT,
        to_rank: typing.Optional[ToRank] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SourcesResponseDto:
        """
        Retrieves the list of sources available in the database. You can filter the sources by language, country, and more.

        Parameters
        ----------
        lang : typing.Optional[Lang]

        countries : typing.Optional[Countries]

        predefined_sources : typing.Optional[PredefinedSources]

        source_name : typing.Optional[SourceName]

        source_url : typing.Optional[SourceUrl]

        include_additional_info : typing.Optional[IncludeAdditionalInfo]

        is_news_domain : typing.Optional[IsNewsDomain]

        news_domain_type : typing.Optional[NewsDomainType]

        news_type : typing.Optional[NewsType]

        from_rank : typing.Optional[FromRank]

        to_rank : typing.Optional[ToRank]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SourcesResponseDto
            A successful response containing a list of news sources that match the specified criteria.

        Examples
        --------
        import asyncio

        from newscatcher import AsyncNewscatcherApi

        client = AsyncNewscatcherApi(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.sources.post(
                predefined_sources=["top 50 US"],
                include_additional_info=True,
                is_news_domain=True,
                news_domain_type="Original Content",
                news_type="General News Outlets",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.post(
            lang=lang,
            countries=countries,
            predefined_sources=predefined_sources,
            source_name=source_name,
            source_url=source_url,
            include_additional_info=include_additional_info,
            is_news_domain=is_news_domain,
            news_domain_type=news_domain_type,
            news_type=news_type,
            from_rank=from_rank,
            to_rank=to_rank,
            request_options=request_options,
        )
        return _response.data
