tesla 0.0.1 → 0.1.0

data/lib/tesla/api/partner_endpoints.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "../json_parsing"
+
+module Tesla
+  module API
+    # The partner endpoints, which act for the application rather than for a user
+    #
+    # They are authorized with a partner token, which each asks the token endpoint for with the client ID and the
+    # client secret of the client (see {OAuthEndpoints#partner_token}).
+    #
+    # @api public
+    module PartnerEndpoints
+      include JSONParsing
+
+      # Register the application in the region of the host
+      #
+      # An application is registered once in each region it is used in, before which the Fleet API of that region
+      # answers its requests with a {PreconditionFailed}. The domain is the one the application was created with
+      # at developer.tesla.com, and has to serve the public key of the application at
+      # `/.well-known/appspecific/com.tesla.3p.public-key.pem`.
+      #
+      # @api public
+      # @authenticated true
+      # @param domain [String] The domain of the application, without a scheme.
+      # @return [Hash{String => Object}] the account the application is registered as
+      # @raise [OAuthError] if the token endpoint turns the request for a partner token away
+      # @example
+      #   Tesla.register_partner "example.com"
+      def register_partner(domain)
+        parse_response(post("/api/1/partner_accounts", {domain:}, headers: partner_headers))
+      end
+
+      # View the public key the application is registered with in the region of the host
+      #
+      # @api public
+      # @authenticated true
+      # @param domain [String] The domain of the application, without a scheme.
+      # @return [String] the public key, as a hexadecimal string
+      # @raise [OAuthError] if the token endpoint turns the request for a partner token away
+      # @raise [InvalidResponse] if the response carries no public key
+      # @example
+      #   Tesla.partner_public_key "example.com"
+      def partner_public_key(domain)
+        body = get("/api/1/partner_accounts/public_key", {domain:}, headers: partner_headers)
+        parse_response(body) { |response| response.fetch("public_key") }
+      end
+
+      private
+
+      # The headers that authorize a request with a partner token
+      #
+      # They replace the header that carries the access token of the client.
+      #
+      # @api private
+      # @return [Hash{String => String}] the headers
+      def partner_headers
+        {"Authorization" => "Bearer #{partner_token.access_token}"}
+      end
+    end
+  end
+end

data/lib/tesla/api/security_endpoints.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Tesla
+  module API
+    # The security commands, which control who can drive a vehicle and how
+    # @api public
+    module SecurityEndpoints
+      # Turn the Sentry 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.
+      # @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_sentry_mode "5YJSA11111111111", on: true
+      def set_sentry_mode(vehicle, on:)
+        command(vehicle, "set_sentry_mode", on:)
+      end
+
+      # Turn the Valet 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 password [String, nil] The four digit PIN that turns Valet Mode off again in the vehicle, or nil for
+      #   none.
+      # @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_valet_mode "5YJSA11111111111", on: true
+      # @example
+      #   Tesla.set_valet_mode "5YJSA11111111111", on: true, password: "1234"
+      def set_valet_mode(vehicle, on:, password: nil)
+        command(vehicle, "set_valet_mode", **{on:, password:}.compact)
+      end
+
+      # Clear the PIN that turns the Valet Mode of a vehicle off
+      #
+      # @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.reset_valet_pin "5YJSA11111111111"
+      def reset_valet_pin(vehicle)
+        command(vehicle, "reset_valet_pin")
+      end
+
+      # Let a vehicle be driven without a key for the next two minutes
+      #
+      # @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.remote_start "5YJSA11111111111"
+      def remote_start(vehicle)
+        command(vehicle, "remote_start_drive")
+      end
+
+      # Set the speed the Speed Limit Mode of a vehicle limits it to
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param mph [Numeric] The speed in miles per hour, from 50 to 120.
+      # @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_speed_limit "5YJSA11111111111", 65
+      def set_speed_limit(vehicle, mph)
+        command(vehicle, "speed_limit_set_limit", limit_mph: mph)
+      end
+
+      # Turn on the Speed Limit Mode of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param pin [String] The four digit PIN that turns Speed Limit Mode off again.
+      # @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.activate_speed_limit "5YJSA11111111111", "1234"
+      def activate_speed_limit(vehicle, pin)
+        command(vehicle, "speed_limit_activate", pin:)
+      end
+
+      # Turn off the Speed Limit Mode of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param pin [String] The four digit PIN Speed Limit Mode was turned on with.
+      # @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.deactivate_speed_limit "5YJSA11111111111", "1234"
+      def deactivate_speed_limit(vehicle, pin)
+        command(vehicle, "speed_limit_deactivate", pin:)
+      end
+
+      # Clear the PIN of the Speed Limit Mode of a vehicle
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param pin [String] The four digit PIN Speed Limit Mode was turned on with.
+      # @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.clear_speed_limit_pin "5YJSA11111111111", "1234"
+      def clear_speed_limit_pin(vehicle, pin)
+        command(vehicle, "speed_limit_clear_pin", pin:)
+      end
+    end
+  end
+end

data/lib/tesla/api/software_endpoints.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Tesla
+  module API
+    # The software commands, which control the software updates of a vehicle
+    # @api public
+    module SoftwareEndpoints
+      # Install the software update a vehicle has downloaded
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param offset [Integer] The seconds to wait before the update is installed, which is none by default.
+      # @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.schedule_software_update "5YJSA11111111111"
+      # @example
+      #   Tesla.schedule_software_update "5YJSA11111111111", offset: 7200
+      def schedule_software_update(vehicle, offset: 0)
+        command(vehicle, "schedule_software_update", offset_sec: offset)
+      end
+
+      # Cancel the software update a vehicle is waiting to install
+      #
+      # @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.cancel_software_update "5YJSA11111111111"
+      def cancel_software_update(vehicle)
+        command(vehicle, "cancel_software_update")
+      end
+    end
+  end
+end

data/lib/tesla/api/user_endpoints.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "../json_parsing"
+require_relative "../region"
+require_relative "../user"
+
+module Tesla
+  module API
+    # The user endpoints, which describe the account an access token was issued for
+    # @api public
+    module UserEndpoints
+      include JSONParsing
+
+      # View the user the access token was issued for
+      #
+      # @api public
+      # @authenticated true
+      # @return [User]
+      # @example
+      #   Tesla.me.email
+      def me
+        User.new(parse_response(get("/api/1/users/me")))
+      end
+
+      # View the region of the Fleet API the account is served by
+      #
+      # A request sent to the host of another region is answered with a {MisdirectedRequest}, so this is the
+      # endpoint that names the host to configure.
+      #
+      # @api public
+      # @authenticated true
+      # @return [Region]
+      # @example
+      #   Tesla.host = Tesla.region.fleet_api_base_url
+      def region
+        Region.new(parse_response(get("/api/1/users/region")))
+      end
+    end
+  end
+end

data/lib/tesla/api/vehicle_endpoints.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require_relative "../errors/vehicle_asleep"
+require_relative "../identifiers"
+require_relative "../json_parsing"
+require_relative "../nearby_charging_sites"
+require_relative "../path_escaping"
+require_relative "../vehicle"
+require_relative "../vehicle_data"
+
+module Tesla
+  module API
+    # The vehicle endpoints, which list the vehicles of an account, read their state, and wake them
+    # @api public
+    module VehicleEndpoints
+      include Identifiers
+      include JSONParsing
+      include PathEscaping
+
+      # The seconds between the requests that ask whether a vehicle being woken is online yet
+      DEFAULT_WAKE_INTERVAL = 2 # seconds
+
+      # List the vehicles of the account
+      #
+      # @api public
+      # @authenticated true
+      # @param page [Integer, nil] The page of vehicles, from 1, or nil for the first.
+      # @param per_page [Integer, nil] The number of vehicles on a page, or nil for the default of the Fleet API.
+      # @return [Array<Vehicle>]
+      # @example
+      #   Tesla.vehicles.map(&:display_name)
+      def vehicles(page: nil, per_page: nil)
+        Vehicle.list(parse_response(get("/api/1/vehicles", {page:, per_page:}.compact)))
+      end
+
+      # View a vehicle of the account
+      #
+      # The vehicle is answered with whatever state it is in, without waking it.
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [Vehicle]
+      # @example
+      #   Tesla.vehicle("5YJSA11111111111").state
+      def vehicle(vehicle)
+        Vehicle.new(parse_response(get(vehicle_path(vehicle))))
+      end
+
+      # Read the state of a vehicle and its subsystems
+      #
+      # The vehicle has to be online to answer (see {#wake_up}).
+      #
+      # The Fleet API answers with the states it is asked for, and leaves the position of the vehicle out of the
+      # ones it answers with by default: it is asked for as "location_data", and answered for an access token with
+      # the vehicle_location scope.
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param endpoints [Array<String, Symbol>, String, Symbol, nil] The states to answer with, among
+      #   "charge_state", "climate_state", "closures_state", "drive_state", "gui_settings", "location_data",
+      #   "charge_schedule_data", "preconditioning_schedule_data", "vehicle_config", and "vehicle_state", or nil for
+      #   the default of the Fleet API.
+      # @return [VehicleData]
+      # @raise [RequestTimeout] if the vehicle is asleep or offline
+      # @example
+      #   Tesla.vehicle_data("5YJSA11111111111").charge_state.battery_level
+      # @example
+      #   Tesla.vehicle_data("5YJSA11111111111", endpoints: %i[location_data drive_state]).drive_state.latitude
+      def vehicle_data(vehicle, endpoints: nil)
+        params = {endpoints: endpoints && [endpoints].join(";")}.compact
+        VehicleData.new(parse_response(get("#{vehicle_path(vehicle)}/vehicle_data", params)))
+      end
+
+      # Wake a vehicle from sleep
+      #
+      # The Fleet API answers before the vehicle has woken, so the vehicle answered with is seldom online. With a
+      # timeout, the vehicle is asked for again every few seconds until it is online, and that is the vehicle
+      # answered with.
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @param timeout [Numeric, nil] The seconds to wait for the vehicle to be online, or nil not to wait.
+      # @param interval [Numeric] The seconds between the requests that ask whether the vehicle is online yet.
+      # @return [Vehicle] the vehicle, which is online when a timeout was given
+      # @raise [VehicleAsleep] if the vehicle is not online once the timeout is over
+      # @example
+      #   Tesla.wake_up "5YJSA11111111111"
+      # @example
+      #   Tesla.wake_up "5YJSA11111111111", timeout: 60
+      def wake_up(vehicle, timeout: nil, interval: DEFAULT_WAKE_INTERVAL)
+        woken = Vehicle.new(parse_response(post("#{vehicle_path(vehicle)}/wake_up")))
+        timeout ? await_online(woken, monotonic_time + timeout, interval) : woken
+      end
+
+      # List the charging sites near a vehicle
+      #
+      # The vehicle has to be online to answer (see {#wake_up}).
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [NearbyChargingSites]
+      # @raise [RequestTimeout] if the vehicle is asleep or offline
+      # @example
+      #   Tesla.nearby_charging_sites("5YJSA11111111111").superchargers.map(&:name)
+      def nearby_charging_sites(vehicle)
+        NearbyChargingSites.new(parse_response(get("#{vehicle_path(vehicle)}/nearby_charging_sites")))
+      end
+
+      # Whether a vehicle allows mobile access
+      #
+      # A vehicle is commanded remotely only while mobile access is enabled in it.
+      #
+      # @api public
+      # @authenticated true
+      # @param vehicle [String, Integer, Vehicle] The VIN or ID of a vehicle, or a vehicle.
+      # @return [Boolean] whether mobile access is enabled in the vehicle
+      # @raise [RequestTimeout] if the vehicle is asleep or offline
+      # @example
+      #   Tesla.mobile_enabled? "5YJSA11111111111"
+      def mobile_enabled?(vehicle)
+        parse_response(get("#{vehicle_path(vehicle)}/mobile_enabled")).eql?(true)
+      end
+
+      private
+
+      # The path of a vehicle
+      #
+      # @api private
+      # @param vehicle [String, Integer, Vehicle] the VIN or ID of a vehicle, or a vehicle
+      # @return [String] the path
+      def vehicle_path(vehicle)
+        "/api/1/vehicles/#{escape(tag_of(vehicle))}"
+      end
+
+      # Ask for a vehicle until it is online
+      #
+      # The vehicle is asked for rather than woken again, since one wake-up is enough to wake a vehicle that can be
+      # woken, and the Fleet API allows fewer of them.
+      #
+      # Kernel#sleep takes any Numeric, but its signature asks for the narrower interface Integer and Float happen to
+      # answer, so the seconds are passed to it unchecked rather than narrowing what the interval accepts.
+      #
+      # @api private
+      # @param woken [Vehicle] the vehicle, as the Fleet API last answered with it
+      # @param deadline [Numeric] the time, on the monotonic clock, the wait is over
+      # @param interval [Numeric] the seconds between the requests
+      # @return [Vehicle] the vehicle, once it is online
+      # @raise [VehicleAsleep] if the vehicle is not online once the wait is over
+      def await_online(woken, deadline, interval)
+        until woken.online?
+          raise VehicleAsleep.new(vehicle: woken) if monotonic_time >= deadline
+
+          sleep(interval) # steep:ignore UnresolvedOverloading
+          woken = vehicle(woken)
+        end
+        woken
+      end
+
+      # The time on the monotonic clock
+      #
+      # A change to the time of the system does not move the monotonic clock, so a wait is measured with it.
+      #
+      # @api private
+      # @return [Float] the seconds since an arbitrary moment
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/tesla/api.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "api/alert_endpoints"
+require_relative "api/charging_endpoints"
+require_relative "api/climate_endpoints"
+require_relative "api/closure_endpoints"
+require_relative "api/command_endpoints"
+require_relative "api/media_endpoints"
+require_relative "api/navigation_endpoints"
+require_relative "api/oauth_endpoints"
+require_relative "api/partner_endpoints"
+require_relative "api/security_endpoints"
+require_relative "api/software_endpoints"
+require_relative "api/user_endpoints"
+require_relative "api/vehicle_endpoints"
+
+module Tesla
+  # The Tesla Fleet API endpoints, mixed into {Client}
+  #
+  # The endpoints are grouped into one mixin per topic. Every public method of those mixins is also available on
+  # the {Tesla} module, which delegates to {Tesla.client}.
+  #
+  # @api public
+  module API
+    include AlertEndpoints
+    include ChargingEndpoints
+    include ClimateEndpoints
+    include ClosureEndpoints
+    include CommandEndpoints
+    include MediaEndpoints
+    include NavigationEndpoints
+    include OAuthEndpoints
+    include PartnerEndpoints
+    include SecurityEndpoints
+    include SoftwareEndpoints
+    include UserEndpoints
+    include VehicleEndpoints
+  end
+end

data/lib/tesla/authenticator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Tesla
+  # Base class for authentication (no authentication)
+  # @api private
+  class Authenticator
+    # The HTTP header name for authentication
+    AUTHENTICATION_HEADER = "Authorization"
+    private_constant :AUTHENTICATION_HEADER
+
+    # Generate the authentication headers for a request
+    #
+    # @api private
+    # @param _request [Net::HTTPRequest] the HTTP request
+    # @return [Hash{String => String}] the authentication headers (empty)
+    # @example Generate empty authentication headers
+    #   authenticator = Tesla::Authenticator.new
+    #   authenticator.header(request)
+    def header(_request)
+      {}
+    end
+
+    # Summarize the authenticator for the console
+    #
+    # @api private
+    # @return [String] the summary, which never includes credentials
+    # @example Inspect an authenticator
+    #   authenticator.inspect # => #<Tesla::Authenticator>
+    def inspect
+      "#<#{self.class}>"
+    end
+  end
+end

data/lib/tesla/bearer_token_authenticator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "authenticator"
+
+module Tesla
+  # Authenticator for OAuth 2.0 bearer token authentication
+  # @api private
+  class BearerTokenAuthenticator < Authenticator
+    # The access token
+    # @api private
+    # @return [String] the access token
+    # @example Get the access token
+    #   authenticator.access_token
+    attr_reader :access_token
+
+    # Initialize a new BearerTokenAuthenticator
+    #
+    # @api private
+    # @param access_token [String] the access token
+    # @return [BearerTokenAuthenticator] a new instance
+    # @example Create a bearer token authenticator
+    #   authenticator = Tesla::BearerTokenAuthenticator.new(access_token: "eyJhbGciOiJSUzI1NiIs")
+    def initialize(access_token:)
+      @access_token = access_token
+    end
+
+    # Generate the authentication headers for a request
+    #
+    # @api private
+    # @param _request [Net::HTTPRequest] the HTTP request
+    # @return [Hash{String => String}] the authentication headers with the access token
+    # @example Generate a bearer token authentication header
+    #   authenticator.header(request)
+    def header(_request)
+      {AUTHENTICATION_HEADER => "Bearer #{access_token}"}
+    end
+  end
+end

data/lib/tesla/certificate_options.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Tesla
+  # The certificates TLS is verified with, mixed into the configuration and the connection
+  #
+  # A host whose certificate Ruby's OpenSSL does not already trust, such as the vehicle command proxy with a
+  # certificate of its own, is reached by naming that certificate here rather than by turning verification off:
+  # there is no option for that, so a request of this library is always verified.
+  #
+  # The path is checked where it is assigned, as a host and a proxy URL are (see {URLValidation}), so that a path
+  # that names nothing is reported as the assignment that was wrong instead of as the TLS failure of the next
+  # request. The value that is rejected is left as it was.
+  #
+  # @api private
+  module CertificateOptions
+    # The path of a file of certificates TLS is verified with
+    #
+    # The certificates in the file are trusted alongside the ones OpenSSL already trusts.
+    #
+    # @api private
+    # @return [String, nil] the path of the file, or nil to verify with the certificates OpenSSL trusts
+    # @example Get the CA file
+    #   connection.ca_file
+    attr_reader :ca_file
+
+    # Set the path of a file of certificates TLS is verified with
+    #
+    # @api private
+    # @param ca_file [String, nil] the path of the file, or nil to verify with the certificates OpenSSL trusts
+    # @return [void]
+    # @raise [ArgumentError] if the path does not name a file, in which case the path is left as it was
+    # @example Set the CA file
+    #   connection.ca_file = "config/tls-cert.pem"
+    def ca_file=(ca_file)
+      @ca_file = ca_file && validate_ca_file(ca_file)
+    end
+
+    private
+
+    # Check that a path names a file of certificates
+    # @api private
+    # @param ca_file [String] the path of the file
+    # @return [String] the path
+    # @raise [ArgumentError] if the path does not name a file
+    def validate_ca_file(ca_file)
+      raise ArgumentError, "Invalid CA file: #{ca_file}" unless File.file?(ca_file)
+
+      ca_file
+    end
+  end
+end