openrouter-python-sdk-retry-errors/src/openrouter/operations/getapprankings.py

"""Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT."""

from __future__ import annotations
from openrouter.components import apprankingsresponse as components_apprankingsresponse
from openrouter.types import BaseModel, UnrecognizedStr
from openrouter.utils import (
    FieldMetadata,
    HeaderMetadata,
    QueryParamMetadata,
    validate_open_enum,
)
import pydantic
from pydantic.functional_validators import PlainValidator
from typing import Awaitable, Callable, Literal, Optional, Union
from typing_extensions import Annotated, NotRequired, TypedDict


class GetAppRankingsGlobalsTypedDict(TypedDict):
    http_referer: NotRequired[str]
    r"""The app identifier should be your app's URL and is used as the primary identifier for rankings.
    This is used to track API usage per application.

    """
    x_open_router_title: NotRequired[str]
    r"""The app display name allows you to customize how your app appears in OpenRouter's dashboard.

    """
    x_open_router_categories: NotRequired[str]
    r"""Comma-separated list of app categories (e.g. \"cli-agent,cloud-agent\"). Used for marketplace rankings.

    """


class GetAppRankingsGlobals(BaseModel):
    http_referer: Annotated[
        Optional[str],
        pydantic.Field(alias="HTTP-Referer"),
        FieldMetadata(header=HeaderMetadata(style="simple", explode=False)),
    ] = None
    r"""The app identifier should be your app's URL and is used as the primary identifier for rankings.
    This is used to track API usage per application.

    """

    x_open_router_title: Annotated[
        Optional[str],
        pydantic.Field(alias="X-OpenRouter-Title"),
        FieldMetadata(header=HeaderMetadata(style="simple", explode=False)),
    ] = None
    r"""The app display name allows you to customize how your app appears in OpenRouter's dashboard.

    """

    x_open_router_categories: Annotated[
        Optional[str],
        pydantic.Field(alias="X-OpenRouter-Categories"),
        FieldMetadata(header=HeaderMetadata(style="simple", explode=False)),
    ] = None
    r"""Comma-separated list of app categories (e.g. \"cli-agent,cloud-agent\"). Used for marketplace rankings.

    """


GetAppRankingsCategory = Union[
    Literal[
        "coding",
        "creative",
        "productivity",
        "entertainment",
    ],
    UnrecognizedStr,
]
r"""Marketplace category group to filter by (e.g. `coding`). Only apps tagged with a subcategory inside this group are returned. Mutually combinable with `subcategory` — when both are supplied the `subcategory` must belong to the `category` group."""


Subcategory = Union[
    Literal[
        "cli-agent",
        "ide-extension",
        "cloud-agent",
        "programming-app",
        "native-app-builder",
        "creative-writing",
        "video-gen",
        "image-gen",
        "audio-gen",
        "roleplay",
        "game",
        "writing-assistant",
        "general-chat",
        "personal-agent",
        "legal",
    ],
    UnrecognizedStr,
]
r"""Marketplace subcategory to filter by (e.g. `cli-agent`). Takes precedence over `category` for the actual filter; when `category` is also supplied the pair must be consistent."""


GetAppRankingsSort = Union[
    Literal[
        "popular",
        "trending",
    ],
    UnrecognizedStr,
]
r"""`popular` ranks apps by total token volume inside the date window. `trending` ranks apps by absolute excess token growth: window volume minus the average volume of the three equal-length periods immediately preceding the window. Apps with no excess growth are omitted from `trending` results."""


class GetAppRankingsRequestTypedDict(TypedDict):
    http_referer: NotRequired[str]
    r"""The app identifier should be your app's URL and is used as the primary identifier for rankings.
    This is used to track API usage per application.

    """
    x_open_router_title: NotRequired[str]
    r"""The app display name allows you to customize how your app appears in OpenRouter's dashboard.

    """
    x_open_router_categories: NotRequired[str]
    r"""Comma-separated list of app categories (e.g. \"cli-agent,cloud-agent\"). Used for marketplace rankings.

    """
    category: NotRequired[GetAppRankingsCategory]
    r"""Marketplace category group to filter by (e.g. `coding`). Only apps tagged with a subcategory inside this group are returned. Mutually combinable with `subcategory` — when both are supplied the `subcategory` must belong to the `category` group."""
    subcategory: NotRequired[Subcategory]
    r"""Marketplace subcategory to filter by (e.g. `cli-agent`). Takes precedence over `category` for the actual filter; when `category` is also supplied the pair must be consistent."""
    sort: NotRequired[GetAppRankingsSort]
    r"""`popular` ranks apps by total token volume inside the date window. `trending` ranks apps by absolute excess token growth: window volume minus the average volume of the three equal-length periods immediately preceding the window. Apps with no excess growth are omitted from `trending` results."""
    start_date: NotRequired[str]
    r"""Start of the date window in YYYY-MM-DD (UTC), inclusive. Defaults to 30 days before `end_date`. The dataset begins at 2025-01-01; earlier values are clamped forward to that floor and the resolved value is echoed in `meta.start_date`."""
    end_date: NotRequired[str]
    r"""End of the date window in YYYY-MM-DD (UTC), inclusive. Defaults to the most recent completed UTC day. Must be on or after 2025-01-01; earlier values are rejected with a 400."""
    limit: NotRequired[int]
    r"""Maximum number of apps to return (1-100). Defaults to 50."""
    offset: NotRequired[int]
    r"""Number of ranked apps to skip before the first returned row (0-100). Defaults to 0. `rank` stays absolute, so the first row of `offset=50` is `rank: 51`."""


class GetAppRankingsRequest(BaseModel):
    http_referer: Annotated[
        Optional[str],
        pydantic.Field(alias="HTTP-Referer"),
        FieldMetadata(header=HeaderMetadata(style="simple", explode=False)),
    ] = None
    r"""The app identifier should be your app's URL and is used as the primary identifier for rankings.
    This is used to track API usage per application.

    """

    x_open_router_title: Annotated[
        Optional[str],
        pydantic.Field(alias="X-OpenRouter-Title"),
        FieldMetadata(header=HeaderMetadata(style="simple", explode=False)),
    ] = None
    r"""The app display name allows you to customize how your app appears in OpenRouter's dashboard.

    """

    x_open_router_categories: Annotated[
        Optional[str],
        pydantic.Field(alias="X-OpenRouter-Categories"),
        FieldMetadata(header=HeaderMetadata(style="simple", explode=False)),
    ] = None
    r"""Comma-separated list of app categories (e.g. \"cli-agent,cloud-agent\"). Used for marketplace rankings.

    """

    category: Annotated[
        Annotated[
            Optional[GetAppRankingsCategory], PlainValidator(validate_open_enum(False))
        ],
        FieldMetadata(query=QueryParamMetadata(style="form", explode=True)),
    ] = None
    r"""Marketplace category group to filter by (e.g. `coding`). Only apps tagged with a subcategory inside this group are returned. Mutually combinable with `subcategory` — when both are supplied the `subcategory` must belong to the `category` group."""

    subcategory: Annotated[
        Annotated[Optional[Subcategory], PlainValidator(validate_open_enum(False))],
        FieldMetadata(query=QueryParamMetadata(style="form", explode=True)),
    ] = None
    r"""Marketplace subcategory to filter by (e.g. `cli-agent`). Takes precedence over `category` for the actual filter; when `category` is also supplied the pair must be consistent."""

    sort: Annotated[
        Annotated[
            Optional[GetAppRankingsSort], PlainValidator(validate_open_enum(False))
        ],
        FieldMetadata(query=QueryParamMetadata(style="form", explode=True)),
    ] = "popular"
    r"""`popular` ranks apps by total token volume inside the date window. `trending` ranks apps by absolute excess token growth: window volume minus the average volume of the three equal-length periods immediately preceding the window. Apps with no excess growth are omitted from `trending` results."""

    start_date: Annotated[
        Optional[str],
        FieldMetadata(query=QueryParamMetadata(style="form", explode=True)),
    ] = None
    r"""Start of the date window in YYYY-MM-DD (UTC), inclusive. Defaults to 30 days before `end_date`. The dataset begins at 2025-01-01; earlier values are clamped forward to that floor and the resolved value is echoed in `meta.start_date`."""

    end_date: Annotated[
        Optional[str],
        FieldMetadata(query=QueryParamMetadata(style="form", explode=True)),
    ] = None
    r"""End of the date window in YYYY-MM-DD (UTC), inclusive. Defaults to the most recent completed UTC day. Must be on or after 2025-01-01; earlier values are rejected with a 400."""

    limit: Annotated[
        Optional[int],
        FieldMetadata(query=QueryParamMetadata(style="form", explode=True)),
    ] = 50
    r"""Maximum number of apps to return (1-100). Defaults to 50."""

    offset: Annotated[
        Optional[int],
        FieldMetadata(query=QueryParamMetadata(style="form", explode=True)),
    ] = 0
    r"""Number of ranked apps to skip before the first returned row (0-100). Defaults to 0. `rank` stays absolute, so the first row of `offset=50` is `rank: 51`."""


class GetAppRankingsResponseTypedDict(TypedDict):
    result: components_apprankingsresponse.AppRankingsResponseTypedDict


class GetAppRankingsResponse(BaseModel):
    next: Union[
        Callable[[], Optional[GetAppRankingsResponse]],
        Callable[[], Awaitable[Optional[GetAppRankingsResponse]]],
    ]

    result: components_apprankingsresponse.AppRankingsResponse