tesla 0.0.1 → 0.1.0

data/lib/tesla/api/climate_endpoints.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Tesla
+  module API
+    # The climate commands, which control the temperature of the cabin and the seats of a vehicle
+    # @api public
+    module ClimateEndpoints
+      # The seats of a vehicle, by the number the Fleet API knows each by
+      #
+      # @api public
+      SEATS = {front_left: 0, front_right: 1, rear_left: 2, rear_left_back: 3, rear_center: 4, rear_right: 5,
+               rear_right_back: 6, third_row_left: 7, third_row_right: 8}.freeze
+
+      # The Climate Keeper modes, by the number the Fleet API knows each by
+      #
+      # Dog Mode and Camp Mode keep the climate control on after the driver has left the vehicle.
+      #
+      # @api public
+      CLIMATE_KEEPER_MODES = {off: 0, on: 1, dog: 2, camp: 3}.freeze
+
+      # Turn on the climate control of a vehicle
+      #
+      # The cabin is heated or cooled to the temperature it is set to (see {#set_temperature}).
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.start_climate "5YJSA11111111111"
+      def start_climate(vehicle)
+        command(vehicle, "auto_conditioning_start")
+      end
+
+      # Turn off the climate control of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.stop_climate "5YJSA11111111111"
+      def stop_climate(vehicle)
+        command(vehicle, "auto_conditioning_stop")
+      end
+
+      # Set the temperature the climate control of a vehicle heats or cools the cabin to
+      #
+      # The temperatures are in degrees Celsius, whatever unit the vehicle displays. The climate control is not turned
+      # on (see {#start_climate}).
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param driver [Numeric] The temperature of the driver's side in degrees Celsius.
+      # @param passenger [Numeric] The temperature of the passenger's side in degrees Celsius, which defaults to
+      #   the driver's.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.set_temperature "5YJSA11111111111", 21.5
+      # @example
+      #   Tesla.set_temperature "5YJSA11111111111", 21.5, 19
+      def set_temperature(vehicle, driver, passenger = driver)
+        command(vehicle, "set_temps", driver_temp: driver, passenger_temp: passenger)
+      end
+
+      # Turn the maximum defrost of a vehicle on or off
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param on [Boolean] Whether to turn it on.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.set_max_defrost "5YJSA11111111111", on: true
+      def set_max_defrost(vehicle, on:)
+        command(vehicle, "set_preconditioning_max", on:)
+      end
+
+      # Set the heater of a seat of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param seat [Symbol, String] The seat, which is one of the seats {SEATS} names.
+      # @param level [Integer] The level of the heater, from 0, which is off, to 3.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @raise [ArgumentError] if the seat is not one the API defines
+      # @example
+      #   Tesla.set_seat_heater "5YJSA11111111111", :front_left, 3
+      def set_seat_heater(vehicle, seat, level)
+        command(vehicle, "remote_seat_heater_request", seat_position: number_of(SEATS, seat, "seat"), level:)
+      end
+
+      # Set the cooler of a seat of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param seat [Symbol, String] The seat, which is one of the seats {SEATS} names.
+      # @param level [Integer] The level of the cooler, from 0, which is off, to 3.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @raise [ArgumentError] if the seat is not one the API defines
+      # @example
+      #   Tesla.set_seat_cooler "5YJSA11111111111", :front_left, 3
+      def set_seat_cooler(vehicle, seat, level)
+        command(vehicle, "remote_seat_cooler_request", seat_position: number_of(SEATS, seat, "seat"), seat_cooler_level: level)
+      end
+
+      # Turn the heater of the steering wheel of a vehicle on or off
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param on [Boolean] Whether to turn it on.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.set_steering_wheel_heater "5YJSA11111111111", on: true
+      def set_steering_wheel_heater(vehicle, on:)
+        command(vehicle, "remote_steering_wheel_heater_request", on:)
+      end
+
+      # Set the Climate Keeper mode of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param mode [Symbol, String] The mode, which is one of the modes {CLIMATE_KEEPER_MODES} names.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @raise [ArgumentError] if the mode is not one the API defines
+      # @example
+      #   Tesla.set_climate_keeper_mode "5YJSA11111111111", :dog
+      def set_climate_keeper_mode(vehicle, mode)
+        mode = number_of(CLIMATE_KEEPER_MODES, mode, "climate keeper mode")
+        command(vehicle, "set_climate_keeper_mode", climate_keeper_mode: mode)
+      end
+
+      # Turn the Bioweapon Defense Mode of a vehicle on or off
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param on [Boolean] Whether to turn it on.
+      # @param manual_override [Boolean] Whether to turn it on although the vehicle would not, such as with a low
+      #   battery.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.set_bioweapon_mode "5YJSA11111111111", on: true
+      def set_bioweapon_mode(vehicle, on:, manual_override: false)
+        command(vehicle, "set_bioweapon_mode", on:, manual_override:)
+      end
+
+      # Turn the Cabin Overheat Protection of a vehicle on or off
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param on [Boolean] Whether to turn it on.
+      # @param fan_only [Boolean] Whether to cool the cabin with the fan alone, without the air conditioning.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.set_cabin_overheat_protection "5YJSA11111111111", on: true
+      # @example
+      #   Tesla.set_cabin_overheat_protection "5YJSA11111111111", on: true, fan_only: true
+      def set_cabin_overheat_protection(vehicle, on:, fan_only: false)
+        command(vehicle, "set_cabin_overheat_protection", on:, fan_only:)
+      end
+    end
+  end
+end

data/lib/tesla/api/closure_endpoints.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Tesla
+  module API
+    # The closure commands, which lock, open, and close the doors, trunks, windows, and sunroof of a vehicle
+    # @api public
+    module ClosureEndpoints
+      # Lock the doors of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.lock_doors "5YJSA11111111111"
+      def lock_doors(vehicle)
+        command(vehicle, "door_lock")
+      end
+
+      # Unlock the doors of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.unlock_doors "5YJSA11111111111"
+      def unlock_doors(vehicle)
+        command(vehicle, "door_unlock")
+      end
+
+      # Open the rear trunk of a vehicle, or close it
+      #
+      # A vehicle with a powered liftgate closes a trunk that is open, so this is the command that pops the trunk and
+      # the one that closes it again. A trunk without one is opened and stays open.
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.actuate_trunk "5YJSA11111111111"
+      def actuate_trunk(vehicle)
+        command(vehicle, "actuate_trunk", which_trunk: "rear")
+      end
+
+      # Open the front trunk of a vehicle
+      #
+      # The front trunk is closed by hand on the vehicles that do not close it themselves.
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.open_frunk "5YJSA11111111111"
+      def open_frunk(vehicle)
+        command(vehicle, "actuate_trunk", which_trunk: "front")
+      end
+
+      # Vent the windows of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.vent_windows "5YJSA11111111111"
+      def vent_windows(vehicle)
+        command(vehicle, "window_control", command: "vent", lat: 0, lon: 0)
+      end
+
+      # Close the windows of a vehicle
+      #
+      # A vehicle that takes the command over the Fleet API rather than through the vehicle command proxy closes its
+      # windows only for a user who is near it, so the position of the user is sent along.
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param latitude [Numeric] The latitude of the user.
+      # @param longitude [Numeric] The longitude of the user.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.close_windows "5YJSA11111111111"
+      # @example
+      #   Tesla.close_windows "5YJSA11111111111", latitude: 37.4929, longitude: -121.9453
+      def close_windows(vehicle, latitude: 0, longitude: 0)
+        command(vehicle, "window_control", command: "close", lat: latitude, lon: longitude)
+      end
+
+      # Vent the sunroof of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.vent_sunroof "5YJSA11111111111"
+      def vent_sunroof(vehicle)
+        command(vehicle, "sun_roof_control", state: "vent")
+      end
+
+      # Close the sunroof of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.close_sunroof "5YJSA11111111111"
+      def close_sunroof(vehicle)
+        command(vehicle, "sun_roof_control", state: "close")
+      end
+
+      # Open or close the garage door a vehicle is paired with over HomeLink
+      #
+      # The vehicle triggers HomeLink only for a user who is near it, so the position of the user is sent along.
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param latitude [Numeric] The latitude of the user.
+      # @param longitude [Numeric] The longitude of the user.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.trigger_homelink "5YJSA11111111111", latitude: 37.4929, longitude: -121.9453
+      def trigger_homelink(vehicle, latitude:, longitude:)
+        command(vehicle, "trigger_homelink", lat: latitude, lon: longitude)
+      end
+    end
+  end
+end

data/lib/tesla/api/command_endpoints.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "../errors/command_failed"
+require_relative "../identifiers"
+require_relative "../json_parsing"
+require_relative "../path_escaping"
+
+module Tesla
+  module API
+    # The command endpoint, which every command of the other mixins is sent through
+    #
+    # A vehicle has to be online to take a command (see {VehicleEndpoints#wake_up}), and most vehicles take only
+    # commands signed with the Tesla Vehicle Command Protocol, which the vehicle command proxy does: a client whose
+    # `host` is the proxy sends its commands through it.
+    #
+    # @api public
+    module CommandEndpoints
+      include Identifiers
+      include JSONParsing
+      include PathEscaping
+
+      # Send a command to a vehicle
+      #
+      # The commands of the other mixins are sent with this, which also sends the commands the library has no
+      # method for.
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param name [String, Symbol] The name of the command, as the Fleet API names it.
+      # @param params [Hash] The parameters of the command.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @raise [RequestTimeout] if the vehicle is asleep or offline
+      # @raise [InvalidResponse] if the response does not say whether the vehicle carried out the command
+      # @example
+      #   Tesla.command "5YJSA11111111111", :set_vehicle_name, vehicle_name: "Nikola 2.0"
+      def command(vehicle, name, **params)
+        body = post("/api/1/vehicles/#{escape(tag_of(vehicle))}/command/#{escape(name)}", params)
+        result, reason = parse_response(body) { |response| [response.fetch("result"), response["reason"]] }
+        raise CommandFailed.new(command: name.to_s, reason:) unless result
+
+        true
+      end
+
+      private
+
+      # Look up the number the Fleet API knows a named option by
+      #
+      # @api private
+      # @param options [Hash{Symbol => Integer}] the numbers of the options, by name
+      # @param name [Symbol, String] the name of the option
+      # @param kind [String] what the option is, which the message names
+      # @return [Integer] the number
+      # @raise [ArgumentError] if the name is not one of the options
+      def number_of(options, name, kind)
+        options.fetch(name.to_sym) do
+          raise ArgumentError, "Unknown #{kind}: #{name}. The #{kind}s the API defines are: #{options.keys.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/tesla/api/media_endpoints.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Tesla
+  module API
+    # The media commands, which control what a vehicle plays
+    # @api public
+    module MediaEndpoints
+      # Play or pause the media of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.toggle_playback "5YJSA11111111111"
+      def toggle_playback(vehicle)
+        command(vehicle, "media_toggle_playback")
+      end
+
+      # Skip to the next track of the media of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.next_track "5YJSA11111111111"
+      def next_track(vehicle)
+        command(vehicle, "media_next_track")
+      end
+
+      # Skip to the previous track of the media of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.previous_track "5YJSA11111111111"
+      def previous_track(vehicle)
+        command(vehicle, "media_prev_track")
+      end
+
+      # Skip to the next favorite of the media of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.next_favorite "5YJSA11111111111"
+      def next_favorite(vehicle)
+        command(vehicle, "media_next_fav")
+      end
+
+      # Skip to the previous favorite of the media of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.previous_favorite "5YJSA11111111111"
+      def previous_favorite(vehicle)
+        command(vehicle, "media_prev_fav")
+      end
+
+      # Turn up the volume of the media of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.volume_up "5YJSA11111111111"
+      def volume_up(vehicle)
+        command(vehicle, "media_volume_up")
+      end
+
+      # Turn down the volume of the media of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.volume_down "5YJSA11111111111"
+      def volume_down(vehicle)
+        command(vehicle, "media_volume_down")
+      end
+
+      # Set the volume of the media of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param volume [Numeric] The volume, from 0 to 11.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.set_volume "5YJSA11111111111", 4.5
+      def set_volume(vehicle, volume)
+        command(vehicle, "adjust_volume", volume:)
+      end
+    end
+  end
+end

data/lib/tesla/api/navigation_endpoints.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Tesla
+  module API
+    # The navigation commands, which send a destination to a vehicle
+    # @api public
+    module NavigationEndpoints
+      # The type of a navigation request, which is the one the Tesla app shares a destination with
+      NAVIGATION_REQUEST_TYPE = "share_ext_content_raw"
+      # The key of the destination of a navigation request
+      NAVIGATION_REQUEST_TEXT = "android.intent.extra.TEXT"
+      private_constant :NAVIGATION_REQUEST_TYPE, :NAVIGATION_REQUEST_TEXT
+
+      # Send a destination to the navigation of a vehicle
+      #
+      # The vehicle searches for the destination as it would for one typed into its navigation, so an address and
+      # the name of a place both work.
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param destination [String] The address or the name of the place to navigate to.
+      # @param locale [String] The locale the destination is written in.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.navigate_to "5YJSA11111111111", "3500 Deer Creek Road, Palo Alto, CA"
+      def navigate_to(vehicle, destination, locale: "en-US")
+        command(vehicle, "navigation_request", type: NAVIGATION_REQUEST_TYPE, locale:,
+          timestamp_ms: Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond),
+          value: {NAVIGATION_REQUEST_TEXT => destination})
+      end
+
+      # Send a position to the navigation of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param latitude [Numeric] The latitude of the destination.
+      # @param longitude [Numeric] The longitude of the destination.
+      # @param order [Integer] The place of the destination among the ones the vehicle is navigating to.
+      # @return [true] once the vehicle has carried out the command
+      # @raise [CommandFailed] if the vehicle answers that it did not carry out the command
+      # @example
+      #   Tesla.navigate_to_coordinates "5YJSA11111111111", 37.3947, -122.1503
+      def navigate_to_coordinates(vehicle, latitude, longitude, order: 1)
+        command(vehicle, "navigation_gps_request", lat: latitude, lon: longitude, order:)
+      end
+    end
+  end
+end

data/lib/tesla/api/oauth_endpoints.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Tesla
+  module API
+    # The OAuth 2.0 endpoints of Tesla's authorization server, which issue the tokens requests are authorized with
+    #
+    # An application is created at developer.tesla.com, which issues its client ID and client secret, and is
+    # registered in a region once (see {PartnerEndpoints#register_partner}). A user is then sent to
+    # {#authorization_url}, and comes back to the redirect URI with a code that {#exchange_code} exchanges for an
+    # access token and a refresh token. The access token lasts eight hours, and the client asks for another with
+    # the refresh token when it runs out (see {#refresh_access_token}).
+    #
+    # The requests are built by the simple_oauth gem, and the tokens are its `SimpleOAuth::OAuth2::Token`.
+    #
+    # @api public
+    module OAuthEndpoints
+      # The scopes a user is asked for by default, which are the ones the endpoints of the library need
+      #
+      # @api public
+      SCOPES = %w[openid offline_access user_data vehicle_device_data vehicle_location vehicle_cmds
+        vehicle_charging_cmds].freeze
+
+      # The scopes a partner token is asked for by default
+      #
+      # @api public
+      PARTNER_SCOPES = %w[openid vehicle_device_data vehicle_cmds vehicle_charging_cmds].freeze
+
+      # The URL a user is sent to in order to authorize the application
+      #
+      # The state is a value of your own that the authorization server hands back with the code, to be compared
+      # with the one sent (see `SimpleOAuth::OAuth2::AuthorizationResponse.parse`).
+      #
+      # @api public
+      # @authenticated false
+      # @param state [String] A random value that ties the response of the authorization server to this request.
+      # @param pkce [SimpleOAuth::OAuth2::PKCE, nil] A PKCE challenge, whose verifier is given to {#exchange_code}.
+      # @param scope [Array<String>, String] The scopes to ask the user for.
+      # @param params [Hash] Other parameters of the authorization request, such as `prompt_missing_scopes`.
+      # @return [String] the URL
+      # @raise [ArgumentError] if the client has no client ID, or the state is empty
+      # @example
+      #   Tesla.authorization_url(state: SecureRandom.hex)
+      def authorization_url(state:, pkce: nil, scope: SCOPES, **params)
+        oauth_client.authorization_url(redirect_uri: required_redirect_uri, pkce:, state:, scope:, params:)
+      end
+
+      # Exchange an authorization code for an access token and a refresh token
+      #
+      # The code is the one the authorization server sent the user back to the redirect URI with.
+      #
+      # The client keeps the tokens, and authorizes its requests with them from then on.
+      #
+      # @api public
+      # @authenticated false
+      # @param code [String] The code the authorization server sent the user back to the redirect URI with.
+      # @param code_verifier [String, nil] The verifier of the PKCE challenge the authorization URL was built with.
+      # @return [SimpleOAuth::OAuth2::Token] the token
+      # @raise [OAuthError] if the token endpoint turns the request away
+      # @raise [ArgumentError] if the client has no client ID or no redirect URI
+      # @example
+      #   token = Tesla.exchange_code(params[:code])
+      #   token.refresh_token
+      def exchange_code(code, code_verifier: nil)
+        request = oauth_client.authorization_code_request(code:, redirect_uri: required_redirect_uri, code_verifier:,
+          params: {audience:})
+        token = request_token(request)
+        exclusively { store_token(token) }
+      end
+
+      # Ask for a new access token with the refresh token
+      #
+      # The client does this itself when the Fleet API answers that its access token is no longer good, so this is
+      # for refreshing ahead of time. The client keeps the tokens it is answered with, the refresh token among
+      # them, since a refresh token is used once.
+      #
+      # @api public
+      # @authenticated false
+      # @return [SimpleOAuth::OAuth2::Token] the token
+      # @raise [OAuthError] if the token endpoint turns the request away
+      # @raise [ArgumentError] if the client has no client ID or no refresh token
+      # @example
+      #   token = Tesla.refresh_access_token
+      #   token.expires_at
+      def refresh_access_token
+        exclusively { refresh }
+      end
+
+      # Ask for a partner token
+      #
+      # A partner token authorizes the endpoints that act for the application rather than for a user.
+      #
+      # The client does not keep the token, since its own requests are authorized by a user.
+      #
+      # @api public
+      # @authenticated false
+      # @param scope [Array<String>, String] The scopes to ask for.
+      # @return [SimpleOAuth::OAuth2::Token] the token
+      # @raise [OAuthError] if the token endpoint turns the request away
+      # @raise [ArgumentError] if the client has no client ID or no client secret
+      # @example
+      #   Tesla.partner_token.access_token
+      def partner_token(scope: PARTNER_SCOPES)
+        request_token(oauth_client.client_credentials_request(scope:, params: {audience:}))
+      end
+
+      private
+
+      # The redirect URI of the client, which has to have one
+      #
+      # @api private
+      # @return [String] the redirect URI
+      # @raise [ArgumentError] if the client has no redirect URI
+      def required_redirect_uri
+        redirect_uri || raise(ArgumentError, "A redirect_uri is required to authorize a user")
+      end
+    end
+  end
+end