from __future__ import annotations

from typing import TypedDict


# ---------------------------------------------------------------------------
# Pagination (shared base)
# ---------------------------------------------------------------------------


class PaginationParams(TypedDict, total=False):
    """Common pagination parameters accepted by all list endpoints."""

    page: int
    per_page: int
    sort: str
    order: str  # "asc" | "desc"


# ---------------------------------------------------------------------------
# Firearms
# ---------------------------------------------------------------------------


class ListFirearmsParams(PaginationParams, total=False):
    """Parameters for ``GET /v1/firearms``."""

    manufacturer: str
    caliber: str
    category: str
    action_type: str
    country_of_origin: str
    year_introduced_min: int
    year_introduced_max: int
    weight_min: float
    weight_max: float
    barrel_length_min: float
    status: str
    has_3d_model: str
    fields: str


class _SearchFirearmsRequired(TypedDict):
    q: str


class SearchFirearmsParams(_SearchFirearmsRequired, PaginationParams, total=False):
    """Parameters for ``GET /v1/firearms/search``."""


class _CompareFirearmsRequired(TypedDict):
    ids: str


class CompareFirearmsParams(_CompareFirearmsRequired, total=False):
    """Parameters for ``GET /v1/firearms/compare``."""


class GameMetaParams(TypedDict, total=False):
    """Parameters for ``GET /v1/firearms/:id/game/meta``."""

    archetype: str


class RandomFirearmParams(TypedDict, total=False):
    """Parameters for ``GET /v1/firearms/random``."""

    category: str
    country: str


class _TopFirearmsRequired(TypedDict):
    stat: str


class TopFirearmsParams(_TopFirearmsRequired, total=False):
    """Parameters for ``GET /v1/firearms/top``."""

    category: str
    limit: int


class _HeadToHeadRequired(TypedDict):
    a: str
    b: str


class HeadToHeadParams(_HeadToHeadRequired, total=False):
    """Parameters for ``GET /v1/firearms/head-to-head``."""


class _ByFeatureRequired(TypedDict):
    feature: str


class ByFeatureParams(_ByFeatureRequired, PaginationParams, total=False):
    """Parameters for ``GET /v1/firearms/by-feature``."""

    category: str


class _ByActionRequired(TypedDict):
    action: str


class ByActionParams(_ByActionRequired, PaginationParams, total=False):
    """Parameters for ``GET /v1/firearms/by-action``."""


class _ByMaterialRequired(TypedDict):
    material: str
    component: str


class ByMaterialParams(_ByMaterialRequired, PaginationParams, total=False):
    """Parameters for ``GET /v1/firearms/by-material``."""


class _ByDesignerRequired(TypedDict):
    designer: str


class ByDesignerParams(_ByDesignerRequired, PaginationParams, total=False):
    """Parameters for ``GET /v1/firearms/by-designer``."""


class PowerRatingParams(PaginationParams, total=False):
    """Parameters for ``GET /v1/firearms/power-rating``."""

    category: str


class TimelineParams(TypedDict, total=False):
    """Parameters for ``GET /v1/firearms/timeline``."""

    page: int
    per_page: int
    sort: str
    order: str
    from_: int  # 'from' is a reserved word
    to: int
    category: str


class _ByConflictRequired(TypedDict):
    conflict: str


class ByConflictParams(_ByConflictRequired, PaginationParams, total=False):
    """Parameters for ``GET /v1/firearms/by-conflict``."""


class _CalculateBallisticsRequired(TypedDict):
    ammo_id: str


class CalculateBallisticsParams(_CalculateBallisticsRequired, total=False):
    """Parameters for ``GET /v1/firearms/:id/calculate``."""


class LoadFirearmParams(TypedDict, total=False):
    """Parameters for ``GET /v1/firearms/:id/load``."""

    ammo_id: str


# ---------------------------------------------------------------------------
# Manufacturers
# ---------------------------------------------------------------------------


class ListManufacturersParams(PaginationParams, total=False):
    """Parameters for ``GET /v1/manufacturers``."""

    country: str


# ---------------------------------------------------------------------------
# Calibers
# ---------------------------------------------------------------------------


class ListCalibersParams(PaginationParams, total=False):
    """Parameters for ``GET /v1/calibers``."""

    cartridge_type: str
    primer_type: str


class _CompareCalibersRequired(TypedDict):
    ids: str


class CompareCalibersParams(_CompareCalibersRequired, total=False):
    """Parameters for ``GET /v1/calibers/compare``."""


class CaliberBallisticsParams(TypedDict, total=False):
    """Parameters for ``GET /v1/calibers/:id/ballistics``."""

    distance: int


# ---------------------------------------------------------------------------
# Ammunition
# ---------------------------------------------------------------------------


class ListAmmunitionParams(PaginationParams, total=False):
    """Parameters for ``GET /v1/ammunition``."""

    caliber_id: str
    bullet_type: str
    is_common: int


class AmmunitionBallisticsParams(TypedDict, total=False):
    """Parameters for ``GET /v1/ammunition/:id/ballistics``."""

    barrel_length_mm: int
    distances: str


# ---------------------------------------------------------------------------
# Stats
# ---------------------------------------------------------------------------


class PopularCalibersParams(TypedDict, total=False):
    """Parameters for ``GET /v1/stats/popular-calibers``."""

    limit: int


class ProlificManufacturersParams(TypedDict, total=False):
    """Parameters for ``GET /v1/stats/prolific-manufacturers``."""

    limit: int
    category: str


class _ByEraRequired(TypedDict):
    decade: str


class ByEraParams(_ByEraRequired, total=False):
    """Parameters for ``GET /v1/stats/by-era``."""


class _AdoptionByCountryRequired(TypedDict):
    code: str


class AdoptionByCountryParams(_AdoptionByCountryRequired, total=False):
    """Parameters for ``GET /v1/stats/adoption/country``."""


class _AdoptionByTypeRequired(TypedDict):
    type: str


class AdoptionByTypeParams(_AdoptionByTypeRequired, total=False):
    """Parameters for ``GET /v1/stats/adoption/type``."""


class ActionTypesParams(TypedDict, total=False):
    """Parameters for ``GET /v1/stats/action-types``."""

    category: str


class FeatureFrequencyParams(TypedDict, total=False):
    """Parameters for ``GET /v1/stats/feature-frequency``."""

    category: str
    limit: int


class CaliberPopularityByEraParams(TypedDict, total=False):
    """Parameters for ``GET /v1/stats/caliber-popularity-by-era``."""

    from_decade: str
    to_decade: str


# ---------------------------------------------------------------------------
# Game
# ---------------------------------------------------------------------------


class BalanceReportParams(TypedDict, total=False):
    """Parameters for ``GET /v1/game/balance``."""

    threshold: int


class TierListParams(TypedDict, total=False):
    """Parameters for ``GET /v1/game/tier-list``."""

    category: str
    stat: str


class _MatchupsRequired(TypedDict):
    a: str
    b: str


class MatchupsParams(_MatchupsRequired, total=False):
    """Parameters for ``GET /v1/game/matchups``."""


class _RoleRosterRequired(TypedDict):
    role: str


class RoleRosterParams(_RoleRosterRequired, total=False):
    """Parameters for ``GET /v1/game/role-roster``."""

    count: int


class _StatDistributionRequired(TypedDict):
    stat: str


class StatDistributionParams(_StatDistributionRequired, total=False):
    """Parameters for ``GET /v1/game/stat-distribution``."""


# ---------------------------------------------------------------------------
# Game Stats Snapshots
# ---------------------------------------------------------------------------


class ListSnapshotFirearmsParams(PaginationParams, total=False):
    """Parameters for ``GET /v1/game-stats/:version/firearms``."""


# ---------------------------------------------------------------------------
# Countries
# ---------------------------------------------------------------------------


class _CountryCodeRequired(TypedDict):
    code: str


class CountryCodeParam(_CountryCodeRequired, total=False):
    """Path parameter for ``GET /v1/countries/:code/arsenal``."""


# ---------------------------------------------------------------------------
# Conflicts
# ---------------------------------------------------------------------------


class ConflictNameQuery(TypedDict, total=False):
    """Parameters for ``GET /v1/conflicts``."""

    name: str


# ---------------------------------------------------------------------------
# Data Quality
# ---------------------------------------------------------------------------


class ConfidenceParams(PaginationParams, total=False):
    """Parameters for ``GET /v1/data/confidence``."""

    below: float


# ---------------------------------------------------------------------------
# Silhouette
# ---------------------------------------------------------------------------


class SilhouetteParams(TypedDict, total=False):
    """Parameters for ``GET /v1/firearms/:id/silhouette``."""

    format: str
    stroke_width: float
    stroke_color: str


# ---------------------------------------------------------------------------
# User-Scoped (via /v1/me)
# ---------------------------------------------------------------------------


class ListFavoritesParams(TypedDict, total=False):
    """Parameters for ``GET /v1/me/favorites``."""

    page: int
    limit: int


class _CreateReportRequired(TypedDict):
    firearm_id: str
    section: str
    issue_type: str
    description: str


class CreateReportParams(_CreateReportRequired, total=False):
    """Body for ``POST /v1/me/reports``."""

    references: list[str]
    suggested_value: str


class ListReportsParams(TypedDict, total=False):
    """Parameters for ``GET /v1/me/reports``."""

    page: int
    per_page: int


class _CreateTicketRequired(TypedDict):
    subject: str
    description: str


class CreateTicketParams(_CreateTicketRequired, total=False):
    """Body for ``POST /v1/me/support``."""

    category: str
    priority: str


class ListTicketsParams(TypedDict, total=False):
    """Parameters for ``GET /v1/me/support``."""

    page: int
    per_page: int
    status: str
    sort: str
    order: str


class _CreateReplyRequired(TypedDict):
    message: str


class CreateReplyParams(_CreateReplyRequired, total=False):
    """Body for ``POST /v1/me/support/:ticketId/replies``."""


class _CreateWebhookRequired(TypedDict):
    url: str
    events: list[str]


class CreateWebhookEndpointParams(_CreateWebhookRequired, total=False):
    """Body for ``POST /v1/me/webhooks``."""

    description: str


class UpdateWebhookEndpointParams(TypedDict, total=False):
    """Body for ``PUT /v1/me/webhooks/:id``."""

    url: str
    description: str | None
    events: list[str]
    active: bool


class ListWebhookEndpointsParams(TypedDict, total=False):
    """Parameters for ``GET /v1/me/webhooks``."""

    page: int
    per_page: int


class UsageParams(TypedDict, total=False):
    """Parameters for ``GET /v1/me/usage``."""

    month: str
    days: int
