client.py

# !!! THIS FILE IS GENERATED BY generate.py
# !!! DO NOT EDIT THIS FILE DIRECTLY
# !!! generated at 2025-06-21 14:24:19.715388+00:00

"""SpaceTraders API v2.3.0

SpaceTraders is an open-universe game and learning platform that
offers a set of HTTP endpoints to control a fleet of ships and explore
a multiplayer universe.

The API is documented using
[OpenAPI](https://github.com/SpaceTradersAPI/api-docs). You can send
your first request right here in your browser to check the status of
the game server.

```json http
{
  "method": "GET",
  "url": "https://api.spacetraders.io/v2",
}
```

Unlike a traditional game, SpaceTraders does not have a first-party
client or app to play the game. Instead, you can use the API to build
your own client, write a script to automate your ships, or try an app
built by the community.

We have a [Discord channel](https://discord.com/invite/jh6zurdWk5)
where you can share your projects, ask questions, and get help from
other players.
"""

from __future__ import annotations

import dataclasses
import datetime as dt
import enum
import typing

import nspess.backend as backend
from nspess.json import Json, JsonFormat, from_json, to_json
import nspess.models as models
import nspess.responses as responses

__all__ = [
    'Client',
]

class Client(backend.Backend):
    SERVER_URL = 'https://api.spacetraders.io/v2'

    #
    # Accounts
    #

    def my_account(self) -> responses.MyAccount:
        """Get Account

        Fetch your account details.
        """

        return self._call(responses.MyAccount, '/my/account')

    def register(self, symbol: str, faction: models.FactionSymbol) -> responses.Register:
        """Register New Agent

        Creates a new agent and ties it to an account.

        The agent symbol must consist of a 3-14 character string, and
        will be used to represent your agent. This symbol will prefix
        the symbol of every ship you own. Agent symbols will be cast
        to all uppercase characters.

        This new agent will be tied to a starting faction of your
        choice, which determines your starting location, and will be
        granted an authorization token, a contract with their starting
        faction, a command ship that can fly across space with
        advanced capabilities, a small probe ship that can be used for
        reconnaissance, and 175,000 credits.

        > #### Keep your token safe and secure
        >
        > Keep careful track of where you store your token. You can
        generate a new token from our account dashboard, but if
        someone else gains access to your token they will be able to
        use it to make API requests on your behalf until the end of
        the reset.

        If you are new to SpaceTraders, It is recommended to register
        with the COSMIC faction, a faction that is well connected to
        the rest of the universe. After registering, you should try
        our interactive [quickstart
        guide](https://docs.spacetraders.io/quickstart/new-game) which
        will walk you through a few basic API requests in just a few
        minutes.
        """

        return self._call(
            responses.Register,
            '/register',
            body = {
                'symbol': to_json(symbol),
                'faction': to_json(faction),
            },
        )

    #
    # Agents
    #

    def agents(self) -> backend.Paged[models.PublicAgent]:
        """List all public agent details."""

        return self._call_paginated(models.PublicAgent, '/agents')

    def agent(self, agent_symbol: str) -> models.PublicAgent:
        """Get public details for a specific agent."""

        return self._call(
            models.PublicAgent,
            '/agents/{agentSymbol:s}',
            pathargs = {
                'agentSymbol': agent_symbol,
            },
        )

    def my_agent(self) -> models.Agent:
        """Get Agent

        Fetch your agent's details.
        """

        return self._call(models.Agent, '/my/agent')

    def my_agent_events(self) -> list[models.AgentEvent]:
        """Get Agent Events

        Get recent events for your agent.
        """

        return self._call(list[models.AgentEvent], '/my/agent/events')

    #
    # Contracts
    #

    def contracts(self) -> backend.Paged[models.Contract]:
        """List Contracts

        Return a paginated list of all your contracts.
        """

        return self._call_paginated(models.Contract, '/my/contracts')

    def contract(self, contract_id: str) -> models.Contract:
        """Get Contract

        Get the details of a specific contract.
        """

        return self._call(
            models.Contract,
            '/my/contracts/{contractId:s}',
            pathargs = {
                'contractId': contract_id,
            },
        )

    def accept_contract(self, contract_id: str) -> responses.AcceptContract:
        """Accept Contract

        Accept a contract by ID.

        You can only accept contracts that were offered to you, were
        not accepted yet, and whose deadlines has not passed yet.
        """

        return self._call(
            responses.AcceptContract,
            '/my/contracts/{contractId:s}/accept',
            pathargs = {
                'contractId': contract_id,
            },
        )

    def fulfill_contract(self, contract_id: str) -> responses.FulfillContract:
        """Fulfill Contract

        Fulfill a contract. Can only be used on contracts that have
        all of their delivery terms fulfilled.
        """

        return self._call(
            responses.FulfillContract,
            '/my/contracts/{contractId:s}/fulfill',
            pathargs = {
                'contractId': contract_id,
            },
        )

    def deliver_contract(self, contract_id: str, ship_symbol: str, trade_symbol: str, units: int) -> responses.DeliverContract:
        """Deliver Cargo to Contract

        Deliver cargo to a contract.

        In order to use this API, a ship must be at the delivery
        location (denoted in the delivery terms as `destinationSymbol`
        of a contract) and must have a number of units of a good
        required by this contract in its cargo.

        Cargo that was delivered will be removed from the ship's
        cargo.
        """

        return self._call(
            responses.DeliverContract,
            '/my/contracts/{contractId:s}/deliver',
            pathargs = {
                'contractId': contract_id,
            },
            body = {
                'shipSymbol': to_json(ship_symbol),
                'tradeSymbol': to_json(trade_symbol),
                'units': to_json(units),
            },
        )

    #
    # Factions
    #

    def factions(self) -> backend.Paged[models.Faction]:
        """List factions

        Return a paginated list of all the factions in the game.
        """

        return self._call_paginated(models.Faction, '/factions')

    def faction(self, faction_symbol: str) -> models.Faction:
        """Faction details

        View the details of a faction.
        """

        return self._call(
            models.Faction,
            '/factions/{factionSymbol:s}',
            pathargs = {
                'factionSymbol': faction_symbol,
            },
        )

    def my_factions(self) -> backend.Paged[responses.MyFaction]:
        """Get My Factions

        Retrieve factions with which the agent has reputation.
        """

        return self._call_paginated(responses.MyFaction, '/my/factions')

    #
    # Fleet
    #

    def my_ships(self) -> backend.Paged[models.Ship]:
        """List Ships

        Return a paginated list of all of ships under your agent's
        ownership.
        """

        return self._call_paginated(models.Ship, '/my/ships')

    def purchase_ship(self, ship_type: models.ShipType, waypoint_symbol: str) -> responses.PurchaseShip:
        """Purchase Ship

        Purchase a ship from a Shipyard. In order to use this
        function, a ship under your agent's ownership must be in a
        waypoint that has the `Shipyard` trait, and the Shipyard must
        sell the type of the desired ship.

        Shipyards typically offer ship types, which are predefined
        templates of ships that have dedicated roles. A template comes
        with a preset of an engine, a reactor, and a frame. It may
        also include a few modules and mounts.
        """

        return self._call(
            responses.PurchaseShip,
            '/my/ships',
            body = {
                'shipType': to_json(ship_type),
                'waypointSymbol': to_json(waypoint_symbol),
            },
        )

    def my_ship(self, ship_symbol: str) -> models.Ship:
        """Get Ship

        Retrieve the details of a ship under your agent's ownership.
        """

        return self._call(
            models.Ship,
            '/my/ships/{shipSymbol:s}',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def create_chart(self, ship_symbol: str) -> responses.CreateChart:
        """Create Chart

        Command a ship to chart the waypoint at its current location.

        Most waypoints in the universe are uncharted by default. These
        waypoints have their traits hidden until they have been
        charted by a ship.

        Charting a waypoint will record your agent as the one who
        created the chart, and all other agents would also be able to
        see the waypoint's traits. Charting a waypoint gives you a one
        time reward of credits based on the rarity of the waypoint's
        traits.
        """

        return self._call(
            responses.CreateChart,
            '/my/ships/{shipSymbol:s}/chart',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    #
    # Fleet, Contracts
    #

    def negotiate_contract(self, ship_symbol: str) -> responses.NegotiateContract:
        """Negotiate Contract

        Negotiate a new contract with the HQ.

        In order to negotiate a new contract, an agent must not have
        ongoing or offered contracts over the allowed maximum amount.
        Currently the maximum contracts an agent can have at a time is
        1.

        Once a contract is negotiated, it is added to the list of
        contracts offered to the agent, which the agent can then
        accept.

        The ship must be present at any waypoint with a faction
        present to negotiate a contract with that faction.
        """

        return self._call(
            responses.NegotiateContract,
            '/my/ships/{shipSymbol:s}/negotiate/contract',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    #
    # Fleet
    #

    def ship_cooldown(self, ship_symbol: str) -> models.Cooldown:
        """Get Ship Cooldown

        Retrieve the details of your ship's reactor cooldown. Some
        actions such as activating your jump drive, scanning, or
        extracting resources taxes your reactor and results in a
        cooldown.

        Your ship cannot perform additional actions until your
        cooldown has expired. The duration of your cooldown is
        relative to the power consumption of the related modules or
        mounts for the action taken.

        Response returns a 204 status code (no-content) when the ship
        has no cooldown.
        """

        return self._call(
            models.Cooldown,
            '/my/ships/{shipSymbol:s}/cooldown',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def dock_ship(self, ship_symbol: str) -> responses.DockShip:
        """Dock Ship

        Attempt to dock your ship at its current location. Docking
        will only succeed if your ship is capable of docking at the
        time of the request.

        Docked ships can access elements in their current location,
        such as the market or a shipyard, but cannot do actions that
        require the ship to be above surface such as navigating or
        extracting.

        The endpoint is idempotent - successive calls will succeed
        even if the ship is already docked.
        """

        return self._call(
            responses.DockShip,
            '/my/ships/{shipSymbol:s}/dock',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def extract_resources(self, ship_symbol: str) -> responses.ExtractResources:
        """Extract Resources

        Extract resources from a waypoint that can be extracted, such
        as asteroid fields, into your ship. Send an optional survey as
        the payload to target specific yields.

        The ship must be in orbit to be able to extract and must have
        mining equipments installed that can extract goods, such as
        the `Gas Siphon` mount for gas-based goods or `Mining Laser`
        mount for ore-based goods.

        The survey property is now deprecated. See the
        `extract/survey` endpoint for more details.
        """

        return self._call(
            responses.ExtractResources,
            '/my/ships/{shipSymbol:s}/extract',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def extract_resources_with_survey(self, ship_symbol: str, survey: models.Survey) -> responses.ExtractResourcesWithSurvey:
        """Extract Resources with Survey

        Use a survey when extracting resources from a waypoint. This
        endpoint requires a survey as the payload, which allows your
        ship to extract specific yields.

        Send the full survey object as the payload which will be
        validated according to the signature. If the signature is
        invalid, or any properties of the survey are changed, the
        request will fail.
        """

        return self._call(
            responses.ExtractResourcesWithSurvey,
            '/my/ships/{shipSymbol:s}/extract/survey',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
            body = to_json(survey),
        )

    def jettison(self, ship_symbol: str, symbol: models.TradeSymbol, units: int) -> responses.Jettison:
        """Jettison Cargo

        Jettison cargo from your ship's cargo hold.
        """

        return self._call(
            responses.Jettison,
            '/my/ships/{shipSymbol:s}/jettison',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
            body = {
                'symbol': to_json(symbol),
                'units': to_json(units),
            },
        )

    def jump_ship(self, ship_symbol: str, waypoint_symbol: str) -> responses.JumpShip:
        """Jump Ship

        Jump your ship instantly to a target connected waypoint. The
        ship must be in orbit to execute a jump.

        A unit of antimatter is purchased and consumed from the market
        when jumping. The price of antimatter is determined by the
        market and is subject to change. A ship can only jump to
        connected waypoints
        """

        return self._call(
            responses.JumpShip,
            '/my/ships/{shipSymbol:s}/jump',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
            body = {
                'waypointSymbol': to_json(waypoint_symbol),
            },
        )

    def create_ship_system_scan(self, ship_symbol: str) -> responses.CreateShipSystemScan:
        """Scan Systems

        Scan for nearby systems, retrieving information on the
        systems' distance from the ship and their waypoints. Requires
        a ship to have the `Sensor Array` mount installed to use.

        The ship will enter a cooldown after using this function,
        during which it cannot execute certain actions.
        """

        return self._call(
            responses.CreateShipSystemScan,
            '/my/ships/{shipSymbol:s}/scan/systems',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def create_ship_waypoint_scan(self, ship_symbol: str) -> responses.CreateShipWaypointScan:
        """Scan Waypoints

        Scan for nearby waypoints, retrieving detailed information on
        each waypoint in range. Scanning uncharted waypoints will
        allow you to ignore their uncharted state and will list the
        waypoints' traits.

        Requires a ship to have the `Sensor Array` mount installed to
        use.

        The ship will enter a cooldown after using this function,
        during which it cannot execute certain actions.
        """

        return self._call(
            responses.CreateShipWaypointScan,
            '/my/ships/{shipSymbol:s}/scan/waypoints',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def create_ship_ship_scan(self, ship_symbol: str) -> responses.CreateShipShipScan:
        """Scan Ships

        Scan for nearby ships, retrieving information for all ships in
        range.

        Requires a ship to have the `Sensor Array` mount installed to
        use.

        The ship will enter a cooldown after using this function,
        during which it cannot execute certain actions.
        """

        return self._call(
            responses.CreateShipShipScan,
            '/my/ships/{shipSymbol:s}/scan/ships',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def scrap_ship(self, ship_symbol: str) -> responses.ScrapShip:
        """Scrap Ship

        Scrap a ship, removing it from the game and receiving a
        portion of the ship's value back in credits. The ship must be
        docked in a waypoint that has the `Shipyard` trait to be
        scrapped.
        """

        return self._call(
            responses.ScrapShip,
            '/my/ships/{shipSymbol:s}/scrap',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def get_scrap_ship(self, ship_symbol: str) -> responses.GetScrapShip:
        """Get Scrap Ship

        Get the value of scrapping a ship. Requires the ship to be
        docked at a waypoint that has the `Shipyard` trait.
        """

        return self._call(
            responses.GetScrapShip,
            '/my/ships/{shipSymbol:s}/scrap',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def navigate_ship(self, ship_symbol: str, waypoint_symbol: str) -> responses.NavigateShip:
        """Navigate Ship

        Navigate to a target destination. The ship must be in orbit to
        use this function. The destination waypoint must be within the
        same system as the ship's current location. Navigating will
        consume the necessary fuel from the ship's manifest based on
        the distance to the target waypoint.

        The returned response will detail the route information
        including the expected time of arrival. Most ship actions are
        unavailable until the ship has arrived at it's destination.

        To travel between systems, see the ship's Warp or Jump
        actions.
        """

        return self._call(
            responses.NavigateShip,
            '/my/ships/{shipSymbol:s}/navigate',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
            body = {
                'waypointSymbol': to_json(waypoint_symbol),
            },
        )

    def warp_ship(self, ship_symbol: str, waypoint_symbol: str) -> responses.WarpShip:
        """Warp Ship

        Warp your ship to a target destination in another system. The
        ship must be in orbit to use this function and must have the
        `Warp Drive` module installed. Warping will consume the
        necessary fuel from the ship's manifest.

        The returned response will detail the route information
        including the expected time of arrival. Most ship actions are
        unavailable until the ship has arrived at its destination.
        """

        return self._call(
            responses.WarpShip,
            '/my/ships/{shipSymbol:s}/warp',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
            body = {
                'waypointSymbol': to_json(waypoint_symbol),
            },
        )

    def orbit_ship(self, ship_symbol: str) -> responses.OrbitShip:
        """Orbit Ship

        Attempt to move your ship into orbit at its current location.
        The request will only succeed if your ship is capable of
        moving into orbit at the time of the request.

        Orbiting ships are able to do actions that require the ship to
        be above surface such as navigating or extracting, but cannot
        access elements in their current waypoint, such as the market
        or a shipyard.

        The endpoint is idempotent - successive calls will succeed
        even if the ship is already in orbit.
        """

        return self._call(
            responses.OrbitShip,
            '/my/ships/{shipSymbol:s}/orbit',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def purchase_cargo(self, ship_symbol: str, symbol: models.TradeSymbol, units: int) -> responses.PurchaseCargo:
        """Purchase Cargo

        Purchase cargo from a market.

        The ship must be docked in a waypoint that has `Marketplace`
        trait, and the market must be selling a good to be able to
        purchase it.

        The maximum amount of units of a good that can be purchased in
        each transaction are denoted by the `tradeVolume` value of the
        good, which can be viewed by using the Get Market action.

        Purchased goods are added to the ship's cargo hold.
        """

        return self._call(
            responses.PurchaseCargo,
            '/my/ships/{shipSymbol:s}/purchase',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
            body = {
                'symbol': to_json(symbol),
                'units': to_json(units),
            },
        )

    def ship_refine(self, ship_symbol: str, produce: responses.Produce) -> responses.ShipRefine:
        """Ship Refine

        Attempt to refine the raw materials on your ship. The request
        will only succeed if your ship is capable of refining at the
        time of the request. In order to be able to refine, a ship
        must have goods that can be refined and have installed a
        `Refinery` module that can refine it.

        When refining, 100 basic goods will be converted into 10
        processed goods.
        """

        return self._call(
            responses.ShipRefine,
            '/my/ships/{shipSymbol:s}/refine',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
            body = {
                'produce': to_json(produce),
            },
        )

    def refuel_ship(self, ship_symbol: str, units: int | None = None, from_cargo: bool | None = None) -> responses.RefuelShip:
        """Refuel Ship

        Refuel your ship by buying fuel from the local market.

        Requires the ship to be docked in a waypoint that has the
        `Marketplace` trait, and the market must be selling fuel in
        order to refuel.

        Each fuel bought from the market replenishes 100 units in your
        ship's fuel.

        Ships will always be refuel to their frame's maximum fuel
        capacity when using this action.
        """

        return self._call(
            responses.RefuelShip,
            '/my/ships/{shipSymbol:s}/refuel',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
            body = {
                'units': to_json(units),
                'fromCargo': to_json(from_cargo),
            },
        )

    def repair_ship(self, ship_symbol: str) -> responses.RepairShip:
        """Repair Ship

        Repair a ship, restoring the ship to maximum condition. The
        ship must be docked at a waypoint that has the `Shipyard`
        trait in order to use this function. To preview the cost of
        repairing the ship, use the Get action.
        """

        return self._call(
            responses.RepairShip,
            '/my/ships/{shipSymbol:s}/repair',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def get_repair_ship(self, ship_symbol: str) -> responses.GetRepairShip:
        """Get Repair Ship

        Get the cost of repairing a ship. Requires the ship to be
        docked at a waypoint that has the `Shipyard` trait.
        """

        return self._call(
            responses.GetRepairShip,
            '/my/ships/{shipSymbol:s}/repair',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def sell_cargo(self, ship_symbol: str, symbol: models.TradeSymbol, units: int) -> responses.SellCargo:
        """Sell Cargo

        Sell cargo in your ship to a market that trades this cargo.
        The ship must be docked in a waypoint that has the
        `Marketplace` trait in order to use this function.
        """

        return self._call(
            responses.SellCargo,
            '/my/ships/{shipSymbol:s}/sell',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
            body = {
                'symbol': to_json(symbol),
                'units': to_json(units),
            },
        )

    def siphon_resources(self, ship_symbol: str) -> responses.SiphonResources:
        """Siphon Resources

        Siphon gases or other resources from gas giants.

        The ship must be in orbit to be able to siphon and must have
        siphon mounts and a gas processor installed.
        """

        return self._call(
            responses.SiphonResources,
            '/my/ships/{shipSymbol:s}/siphon',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def create_survey(self, ship_symbol: str) -> responses.CreateSurvey:
        """Create Survey

        Create surveys on a waypoint that can be extracted such as
        asteroid fields. A survey focuses on specific types of
        deposits from the extracted location. When ships extract using
        this survey, they are guaranteed to procure a high amount of
        one of the goods in the survey.

        In order to use a survey, send the entire survey details in
        the body of the extract request.

        Each survey may have multiple deposits, and if a symbol shows
        up more than once, that indicates a higher chance of
        extracting that resource.

        Your ship will enter a cooldown after surveying in which it is
        unable to perform certain actions. Surveys will eventually
        expire after a period of time or will be exhausted after being
        extracted several times based on the survey's size. Multiple
        ships can use the same survey for extraction.

        A ship must have the `Surveyor` mount installed in order to
        use this function.
        """

        return self._call(
            responses.CreateSurvey,
            '/my/ships/{shipSymbol:s}/survey',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def transfer_cargo(self, from_ship: str, trade_symbol: models.TradeSymbol, units: int, to_ship: str) -> responses.TransferCargo:
        """Transfer Cargo

        Transfer cargo between ships.

        The receiving ship must be in the same waypoint as the
        transferring ship, and it must able to hold the additional
        cargo after the transfer is complete. Both ships also must be
        in the same state, either both are docked or both are
        orbiting.

        The response body's cargo shows the cargo of the transferring
        ship after the transfer is complete.
        """

        return self._call(
            responses.TransferCargo,
            '/my/ships/{shipSymbol:s}/transfer',
            pathargs = {
                'shipSymbol': from_ship,
            },
            body = {
                'tradeSymbol': to_json(trade_symbol),
                'units': to_json(units),
                'shipSymbol': to_json(to_ship),
            },
        )

    def my_ship_cargo(self, ship_symbol: str) -> models.ShipCargo:
        """Get Ship Cargo

        Retrieve the cargo of a ship under your agent's ownership.
        """

        return self._call(
            models.ShipCargo,
            '/my/ships/{shipSymbol:s}/cargo',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def ship_modules(self, ship_symbol: str) -> list[models.ShipModule]:
        """Get Ship Modules

        Get the modules installed on a ship.
        """

        return self._call(
            list[models.ShipModule],
            '/my/ships/{shipSymbol:s}/modules',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def install_ship_module(self, ship_symbol: str, symbol: str) -> responses.InstallShipModule:
        """Install Ship Module

        Install a module on a ship. The module must be in your cargo.
        """

        return self._call(
            responses.InstallShipModule,
            '/my/ships/{shipSymbol:s}/modules/install',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
            body = {
                'symbol': to_json(symbol),
            },
        )

    def remove_ship_module(self, ship_symbol: str, symbol: str) -> responses.RemoveShipModule:
        """Remove Ship Module

        Remove a module from a ship. The module will be placed in
        cargo.
        """

        return self._call(
            responses.RemoveShipModule,
            '/my/ships/{shipSymbol:s}/modules/remove',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
            body = {
                'symbol': to_json(symbol),
            },
        )

    def mounts(self, ship_symbol: str) -> list[models.ShipMount]:
        """Get Mounts

        Get the mounts installed on a ship.
        """

        return self._call(
            list[models.ShipMount],
            '/my/ships/{shipSymbol:s}/mounts',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def install_mount(self, ship_symbol: str, symbol: str) -> responses.InstallMount:
        """Install Mount

        Install a mount on a ship.

        In order to install a mount, the ship must be docked and
        located in a waypoint that has a `Shipyard` trait. The ship
        also must have the mount to install in its cargo hold.

        An installation fee will be deduced by the Shipyard for
        installing the mount on the ship.
        """

        return self._call(
            responses.InstallMount,
            '/my/ships/{shipSymbol:s}/mounts/install',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
            body = {
                'symbol': to_json(symbol),
            },
        )

    def remove_mount(self, ship_symbol: str, symbol: str) -> responses.RemoveMount:
        """Remove Mount

        Remove a mount from a ship.

        The ship must be docked in a waypoint that has the `Shipyard`
        trait, and must have the desired mount that it wish to remove
        installed.

        A removal fee will be deduced from the agent by the Shipyard.
        """

        return self._call(
            responses.RemoveMount,
            '/my/ships/{shipSymbol:s}/mounts/remove',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
            body = {
                'symbol': to_json(symbol),
            },
        )

    def ship_nav(self, ship_symbol: str) -> models.ShipNav:
        """Get Ship Nav

        Get the current nav status of a ship.
        """

        return self._call(
            models.ShipNav,
            '/my/ships/{shipSymbol:s}/nav',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
        )

    def patch_ship_nav(self, ship_symbol: str, flight_mode: models.ShipNavFlightMode | None = None) -> responses.PatchShipNav:
        """Patch Ship Nav

        Update the nav configuration of a ship.

        Currently only supports configuring the Flight Mode of the
        ship, which affects its speed and fuel consumption.
        """

        return self._call(
            responses.PatchShipNav,
            '/my/ships/{shipSymbol:s}/nav',
            pathargs = {
                'shipSymbol': ship_symbol,
            },
            body = {
                'flightMode': to_json(flight_mode),
            },
        )

    #
    # Systems
    #

    def systems(self) -> backend.Paged[models.System]:
        """List Systems

        Return a paginated list of all systems.
        """

        return self._call_paginated(models.System, '/systems')

    def system(self, system_symbol: str) -> models.System:
        """Get System

        Get the details of a system. Requires the system to have been
        visited or charted.
        """

        return self._call(
            models.System,
            '/systems/{systemSymbol:s}',
            pathargs = {
                'systemSymbol': system_symbol,
            },
        )

    def system_waypoints(self, system_symbol: str, type: Json | None = None, traits: Json | None = None) -> backend.Paged[models.Waypoint]:
        """List Waypoints in System

        Return a paginated list of all of the waypoints for a given
        system.

        If a waypoint is uncharted, it will return the `Uncharted`
        trait instead of its actual traits.
        """

        return self._call_paginated(
            models.Waypoint,
            '/systems/{systemSymbol:s}/waypoints',
            pathargs = {
                'systemSymbol': system_symbol,
            },
            queryargs = {
                'type': str(type) if type is not None else None,
                'traits': str(traits) if traits is not None else None,
            },
        )

    def waypoint(self, system_symbol: str, waypoint_symbol: str) -> models.Waypoint:
        """Get Waypoint

        View the details of a waypoint.

        If the waypoint is uncharted, it will return the 'Uncharted'
        trait instead of its actual traits.
        """

        return self._call(
            models.Waypoint,
            '/systems/{systemSymbol:s}/waypoints/{waypointSymbol:s}',
            pathargs = {
                'systemSymbol': system_symbol,
                'waypointSymbol': waypoint_symbol,
            },
        )

    def construction(self, system_symbol: str, waypoint_symbol: str) -> models.Construction:
        """Get Construction Site

        Get construction details for a waypoint. Requires a waypoint
        with a property of `isUnderConstruction` to be true.
        """

        return self._call(
            models.Construction,
            '/systems/{systemSymbol:s}/waypoints/{waypointSymbol:s}/construction',
            pathargs = {
                'systemSymbol': system_symbol,
                'waypointSymbol': waypoint_symbol,
            },
        )

    def supply_construction(self, system_symbol: str, waypoint_symbol: str, ship_symbol: str, trade_symbol: Json, units: int) -> responses.SupplyConstruction:
        """Supply Construction Site

        Supply a construction site with the specified good. Requires a
        waypoint with a property of `isUnderConstruction` to be true.

        The good must be in your ship's cargo. The good will be
        removed from your ship's cargo and added to the construction
        site's materials.
        """

        return self._call(
            responses.SupplyConstruction,
            '/systems/{systemSymbol:s}/waypoints/{waypointSymbol:s}/construction/supply',
            pathargs = {
                'systemSymbol': system_symbol,
                'waypointSymbol': waypoint_symbol,
            },
            body = {
                'shipSymbol': to_json(ship_symbol),
                'tradeSymbol': to_json(trade_symbol),
                'units': to_json(units),
            },
        )

    def market(self, system_symbol: str, waypoint_symbol: str) -> models.Market:
        """Get Market

        Retrieve imports, exports and exchange data from a
        marketplace. Requires a waypoint that has the `Marketplace`
        trait to use.

        Send a ship to the waypoint to access trade good prices and
        recent transactions. Refer to the [Market Overview
        page](https://docs.spacetraders.io/game-concepts/markets) to
        gain better a understanding of the market in the game.
        """

        return self._call(
            models.Market,
            '/systems/{systemSymbol:s}/waypoints/{waypointSymbol:s}/market',
            pathargs = {
                'systemSymbol': system_symbol,
                'waypointSymbol': waypoint_symbol,
            },
        )

    def jump_gate(self, system_symbol: str, waypoint_symbol: str) -> models.JumpGate:
        """Get Jump Gate

        Get jump gate details for a waypoint. Requires a waypoint of
        type `JUMP_GATE` to use.

        Waypoints connected to this jump gate can be found by querying
        the waypoints in the system.
        """

        return self._call(
            models.JumpGate,
            '/systems/{systemSymbol:s}/waypoints/{waypointSymbol:s}/jump-gate',
            pathargs = {
                'systemSymbol': system_symbol,
                'waypointSymbol': waypoint_symbol,
            },
        )

    def shipyard(self, system_symbol: str, waypoint_symbol: str) -> models.Shipyard:
        """Get Shipyard

        Get the shipyard for a waypoint. Requires a waypoint that has
        the `Shipyard` trait to use. Send a ship to the waypoint to
        access data on ships that are currently available for purchase
        and recent transactions.
        """

        return self._call(
            models.Shipyard,
            '/systems/{systemSymbol:s}/waypoints/{waypointSymbol:s}/shipyard',
            pathargs = {
                'systemSymbol': system_symbol,
                'waypointSymbol': waypoint_symbol,
            },
        )

    #
    # Global
    #

    def status(self) -> responses.Status:
        """Server status

        Return the status of the game server.

        This also includes a few global elements, such as
        announcements, server reset dates and leaderboards.
        """

        return self._call(
            responses.Status,
            '/',
            adhoc = True,
        )

    def error_codes(self) -> responses.ErrorCodes:
        """Error code list

        Return a list of all possible error codes thrown by the game
        server.
        """

        return self._call(
            responses.ErrorCodes,
            '/error-codes',
            adhoc = True,
        )