# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

from __future__ import annotations

from typing import Union, Optional
from datetime import date
from typing_extensions import Literal, Required, Annotated, TypedDict

from .._types import SequenceNotStr
from .._utils import PropertyInfo

__all__ = ["WebSearchParams", "DateRange"]


class WebSearchParams(TypedDict, total=False):
    query: Required[str]
    """Base search query text.

    You can include inline search operators here, such as exact phrases (`"..."`),
    excluded terms (`-term`), file extension filters (`filetype:pdf`), URL matching
    (`inurl:` and `allinurl:`), title matching (`intitle:` and `allintitle:`), and
    related-site lookup (`related:`). Prefer `include_domains` and `exclude_domains`
    over manually adding `site:` operators. Use `date_range` for time filtering
    instead of embedding time operators in the query.
    """

    search_type: Required[Literal["all", "news"]]
    """Search source to query.

    Use `all` to request both `web` and `news` results in one call, or `news` for
    news-only results. There is currently no `web`-only option. This field is
    required and has no server-side default.
    """

    date_range: Optional[DateRange]
    """Optional inclusive date range filter converted into Firecrawl's `tbs` parameter.

    This affects `web` results only and does not filter `news` results.
    """

    exclude_domains: SequenceNotStr[str]
    """Additional domains to exclude from results.

    Each domain is converted into a `-site:` operator and merged with the default
    denylist.
    """

    include_domains: SequenceNotStr[str]
    """Optional domains to require in results.

    Each domain is converted into a `site:` operator and appended to the query.
    """

    limit: int
    """Maximum number of results requested per upstream source.

    With `search_type="all"`, up to this many `web` results and this many `news`
    results may be returned.
    """


class DateRange(TypedDict, total=False):
    """Optional inclusive date range filter converted into Firecrawl's `tbs` parameter.

    This affects `web` results only and does not filter `news` results.
    """

    end_date: Required[Annotated[Union[str, date], PropertyInfo(format="iso8601")]]
    """Inclusive end date for filtering web search results."""

    start_date: Required[Annotated[Union[str, date], PropertyInfo(format="iso8601")]]
    """Inclusive start date for filtering web search results."""
