tesla 0.0.1 → 0.1.0

data/lib/tesla/errors/client_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "http_error"
+
+module Tesla
+  # Base class for client errors (4xx HTTP status codes)
+  # @api public
+  class ClientError < HTTPError; end
+end

data/lib/tesla/errors/command_failed.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Tesla
+  # Error raised when a vehicle answers a command by saying it did not carry it out
+  #
+  # A command the Fleet API could not deliver, such as one sent to a vehicle that is asleep, is answered with an
+  # HTTP status and raises the {HTTPError} of that status. This is the error of a command that was delivered: the
+  # vehicle read it and refused, such as a charge that cannot be started because no cable is connected.
+  #
+  # @api public
+  class CommandFailed < Error
+    # The command the vehicle did not carry out
+    # @api public
+    # @return [String] the name of the command, as the Fleet API names it
+    # @example Get the command
+    #   error.command # => "charge_start"
+    attr_reader :command
+
+    # The reason the vehicle gave
+    # @api public
+    # @return [String] the reason, which is empty when the vehicle gave none
+    # @example Get the reason
+    #   error.reason # => "disconnected"
+    attr_reader :reason
+
+    # Initialize a new CommandFailed
+    #
+    # @api public
+    # @param command [String] the name of the command, as the Fleet API names it
+    # @param reason [String, nil] the reason the vehicle gave
+    # @return [CommandFailed] a new instance
+    # @example Create a command failed error
+    #   Tesla::CommandFailed.new(command: "charge_start", reason: "disconnected")
+    def initialize(command:, reason:)
+      @command = command
+      @reason = reason.to_s
+      super(["The vehicle did not carry out #{command}", @reason].reject(&:empty?).join(": "))
+    end
+  end
+end

data/lib/tesla/errors/device_unexpected_response.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "server_error"
+
+module Tesla
+  # Error raised for HTTP 540 responses, which the Fleet API answers with when the vehicle answered with an error
+  #
+  # The vehicle may need to be restarted, updated, or serviced.
+  #
+  # @api public
+  class DeviceUnexpectedResponse < ServerError; end
+end

data/lib/tesla/errors/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Tesla
+  # Base error class for all Tesla errors
+  # @api public
+  class Error < StandardError; end
+end

data/lib/tesla/errors/forbidden.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Tesla
+  # Error raised for HTTP 403 Forbidden responses
+  #
+  # The Fleet API answers with it when the access token lacks the scope an endpoint requires, and when a command is
+  # sent to a vehicle that takes commands only over the Tesla Vehicle Command Protocol, which signs them: such a
+  # vehicle is commanded through the vehicle command proxy, which the client is pointed at with `host`.
+  #
+  # @api public
+  class Forbidden < ClientError; end
+end

data/lib/tesla/errors/gateway_timeout.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "server_error"
+
+module Tesla
+  # Error raised for HTTP 504 Gateway Timeout responses
+  # @api public
+  class GatewayTimeout < ServerError; end
+end

data/lib/tesla/errors/http_error.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require_relative "../retry_after"
+require_relative "error"
+
+module Tesla
+  # Base class for HTTP errors from the Tesla Fleet API
+  # @api public
+  class HTTPError < Error
+    include RetryAfter
+
+    # The HTTP response
+    # @api public
+    # @return [Net::HTTPResponse] the HTTP response
+    # @example Get the response
+    #   error.response
+    attr_reader :response
+
+    # The HTTP status code
+    # @api public
+    # @return [Integer] the HTTP status code
+    # @example Get the status code
+    #   error.code
+    attr_reader :code
+
+    # Initialize a new HTTPError
+    #
+    # The message is the error the Fleet API describes in the JSON of the response body, which is its `error` and
+    # its `error_description`. A body that describes no error is the message as it is, and the status message
+    # stands in for a body that is empty or an HTML page, such as the error page of a CDN.
+    #
+    # @api public
+    # @param response [Net::HTTPResponse] the HTTP response
+    # @return [HTTPError] a new instance
+    # @example Create an HTTP error
+    #   error = Tesla::HTTPError.new(response: response)
+    def initialize(response:)
+      super(error_message(response))
+      @response = response
+      @code = Integer(response.code)
+    end
+
+    # The seconds to wait before retrying the request
+    #
+    # The Fleet API sends a Retry-After header with a 429 Too Many Requests response, as a number of seconds or an
+    # HTTP date.
+    #
+    # @api public
+    # @return [Integer, nil] the seconds to wait, rounded up and never negative, or nil when the response has no
+    #   Retry-After header or one that is neither a number of seconds nor an HTTP date
+    # @example Wait before retrying
+    #   sleep(error.retry_after || 1)
+    def retry_after
+      retry_after_of(response)
+    end
+
+    private
+
+    # Get the error message from the response
+    # @api private
+    # @param response [Net::HTTPResponse] the HTTP response
+    # @return [String] the error the body describes, else the body, else the status message if the body is empty or
+    #   an HTML page
+    def error_message(response)
+      body = response.body.to_s
+      return response.message if body.empty? || response.content_type&.casecmp?("text/html")
+
+      described_error(body) || body
+    end
+
+    # The error a JSON response body describes
+    #
+    # The Fleet API answers an error with a short identifier as the `error` of a JSON object, and sometimes more
+    # about it as the `error_description`.
+    #
+    # @api private
+    # @param body [String] the response body
+    # @return [String, nil] the error and its description, or nil when the body is not JSON or describes no error
+    def described_error(body)
+      error = Hash.try_convert(JSON.parse(body)) || {}
+      details = error.values_at("error", "error_description").map(&:to_s).reject(&:empty?)
+      details.join(": ") unless details.empty?
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/tesla/errors/internal_server_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "server_error"
+
+module Tesla
+  # Error raised for HTTP 500 Internal Server Error responses
+  # @api public
+  class InternalServerError < ServerError; end
+end

data/lib/tesla/errors/invalid_response.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Tesla
+  # Error raised when a successful response cannot be read: its body is not JSON, such as the page of a proxy or
+  # captive portal, its JSON lacks a field the library reads or has one of another type, or a timestamp in it cannot
+  # be parsed
+  # @api public
+  class InvalidResponse < Error
+    # The text that could not be read
+    # @api public
+    # @return [String] the response body, or the value of the attribute, that could not be read
+    # @example Get the body
+    #   error.body
+    attr_reader :body
+
+    # Initialize a new InvalidResponse
+    #
+    # @api public
+    # @param body [String] the response body, or the value of the attribute, that could not be read
+    # @param message [String] the error message
+    # @return [InvalidResponse] a new instance
+    # @example Create an invalid response error
+    #   Tesla::InvalidResponse.new(body: "<html>")
+    # @example Create an invalid response error for a missing field
+    #   Tesla::InvalidResponse.new(body: "{}", message: "The response body has no version")
+    def initialize(body:, message: "The response body is not JSON")
+      super(message)
+      @body = body
+    end
+  end
+end

data/lib/tesla/errors/locked.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Tesla
+  # Error raised for HTTP 423 Locked responses
+  #
+  # The Fleet API answers with it when Tesla has locked the account.
+  #
+  # @api public
+  class Locked < ClientError; end
+end

data/lib/tesla/errors/method_not_allowed.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Tesla
+  # Error raised for HTTP 405 Method Not Allowed responses
+  # @api public
+  class MethodNotAllowed < ClientError; end
+end

data/lib/tesla/errors/misdirected_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Tesla
+  # Error raised for HTTP 421 Misdirected Request responses
+  #
+  # The Fleet API answers with it when the account belongs to another region than the host of the request serves
+  # (see {API::UserEndpoints#region}).
+  #
+  # @api public
+  class MisdirectedRequest < ClientError; end
+end

data/lib/tesla/errors/network_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "timeout"
+require "zlib"
+require_relative "error"
+
+module Tesla
+  # Error raised when a network error occurs
+  # @api public
+  class NetworkError < Error
+    # The errors of Net::HTTP, and of the socket and TLS layers under it, that are raised as a NetworkError
+    #
+    # One of these is the `cause` of every NetworkError, so a timeout worth trying again can be told from a
+    # connection that was refused.
+    #
+    # @api public
+    WRAPPED = [
+      IOError,
+      Net::HTTPBadResponse,
+      Net::ProtocolError,
+      OpenSSL::SSL::SSLError,
+      SocketError,
+      SystemCallError,
+      Timeout::Error,
+      Zlib::Error
+    ].freeze
+  end
+end

data/lib/tesla/errors/not_acceptable.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Tesla
+  # Error raised for HTTP 406 Not Acceptable responses
+  # @api public
+  class NotAcceptable < ClientError; end
+end

data/lib/tesla/errors/not_found.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Tesla
+  # Error raised for HTTP 404 Not Found responses
+  # @api public
+  class NotFound < ClientError; end
+end

data/lib/tesla/errors/oauth_error.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Tesla
+  # Error raised when the token endpoint of Tesla's authorization server turns a request away, or answers with a
+  # response no token can be read from
+  #
+  # The error of the simple_oauth gem, which reads the response, is its `cause`.
+  #
+  # @api public
+  class OAuthError < Error
+    # The error code the token endpoint answered with
+    # @api public
+    # @return [String, nil] the error code, such as "invalid_grant", or nil when the response carried none
+    # @example Get the error code
+    #   error.code # => "invalid_grant"
+    attr_reader :code
+
+    # The description the token endpoint answered with
+    # @api public
+    # @return [String, nil] the description, or nil when the response carried none
+    # @example Get the description
+    #   error.description # => "The refresh token is expired."
+    attr_reader :description
+
+    # The HTTP status the token endpoint answered with
+    # @api public
+    # @return [Integer, nil] the HTTP status
+    # @example Get the status
+    #   error.status # => 401
+    attr_reader :status
+
+    # Initialize a new OAuthError
+    #
+    # The message is the error code and the description, or names the status when the response carried neither.
+    #
+    # @api public
+    # @param code [String, nil] the error code the token endpoint answered with
+    # @param description [String, nil] the description the token endpoint answered with
+    # @param status [Integer, nil] the HTTP status the token endpoint answered with
+    # @return [OAuthError] a new instance
+    # @example Create an OAuth error
+    #   Tesla::OAuthError.new(code: "invalid_grant", description: "The refresh token is expired.", status: 401)
+    def initialize(code: nil, description: nil, status: nil)
+      @code = code
+      @description = description
+      @status = status
+      details = [code, description].compact
+      super(details.empty? ? "The token endpoint answered with status #{status}" : details.join(": "))
+    end
+  end
+end

data/lib/tesla/errors/payment_required.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Tesla
+  # Error raised for HTTP 402 Payment Required responses
+  #
+  # The Fleet API answers with it when the account of the application has a bill to pay before it is served again.
+  #
+  # @api public
+  class PaymentRequired < ClientError; end
+end

data/lib/tesla/errors/precondition_failed.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Tesla
+  # Error raised for HTTP 412 Precondition Failed responses
+  #
+  # The Fleet API answers with it when the application has not been registered in the region of the request (see
+  # {API::PartnerEndpoints#register_partner}).
+  #
+  # @api public
+  class PreconditionFailed < ClientError; end
+end

data/lib/tesla/errors/request_timeout.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Tesla
+  # Error raised for HTTP 408 Request Timeout responses
+  #
+  # The Fleet API answers with it when the vehicle is asleep or offline, so it is the error of a command or a data
+  # request sent to a vehicle that has not been woken (see {API::VehicleEndpoints#wake_up}).
+  #
+  # @api public
+  class RequestTimeout < ClientError; end
+end

data/lib/tesla/errors/server_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "http_error"
+
+module Tesla
+  # Base class for server errors (5xx HTTP status codes)
+  # @api public
+  class ServerError < HTTPError; end
+end

data/lib/tesla/errors/service_unavailable.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "server_error"
+
+module Tesla
+  # Error raised for HTTP 503 Service Unavailable responses
+  # @api public
+  class ServiceUnavailable < ServerError; end
+end

data/lib/tesla/errors/too_many_redirects.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Tesla
+  # Error raised when too many redirects are encountered
+  # @api public
+  class TooManyRedirects < Error; end
+end

data/lib/tesla/errors/too_many_requests.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Tesla
+  # Error raised for HTTP 429 Too Many Requests responses
+  # @api public
+  class TooManyRequests < ClientError; end
+end

data/lib/tesla/errors/unauthorized.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Tesla
+  # Error raised for HTTP 401 Unauthorized responses
+  # @api public
+  class Unauthorized < ClientError; end
+end

data/lib/tesla/errors/unavailable_for_legal_reasons.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Tesla
+  # Error raised for HTTP 451 Unavailable For Legal Reasons responses
+  #
+  # The Fleet API answers with it when a privacy setting of the vehicle or the account withholds what was asked for.
+  #
+  # @api public
+  class UnavailableForLegalReasons < ClientError; end
+end

data/lib/tesla/errors/unprocessable_content.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Tesla
+  # Error raised for HTTP 422 Unprocessable Content responses
+  #
+  # RFC 9110 names the status Unprocessable Content, where the RFCs before it named it Unprocessable Entity.
+  #
+  # @api public
+  class UnprocessableContent < ClientError; end
+end

data/lib/tesla/errors/vehicle_asleep.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Tesla
+  # Error raised when a vehicle that was woken is still not online once the wait for it is over
+  #
+  # A vehicle can take a minute to wake, and one without a connection, such as one parked underground, does not
+  # wake at all.
+  #
+  # @api public
+  class VehicleAsleep < Error
+    # The vehicle as the Fleet API last answered with it
+    # @api public
+    # @return [Vehicle] the vehicle, whose state says why it is not online
+    # @example Get the state the vehicle was last in
+    #   error.vehicle.state # => "asleep"
+    attr_reader :vehicle
+
+    # Initialize a new VehicleAsleep
+    #
+    # @api public
+    # @param vehicle [Vehicle] the vehicle as the Fleet API last answered with it
+    # @return [VehicleAsleep] a new instance
+    # @example Create a vehicle asleep error
+    #   Tesla::VehicleAsleep.new(vehicle: vehicle)
+    def initialize(vehicle:)
+      @vehicle = vehicle
+      super("The vehicle is still #{vehicle.state.inspect} rather than online")
+    end
+  end
+end

data/lib/tesla/gui_settings.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Tesla
+  # The units and formats a vehicle displays
+  # @api public
+  class GUISettings < Resource
+    inspect_with :distance_units, :temperature_units
+
+    # @!method distance_units
+    #   The unit of distance the vehicle displays, "mi/hr" or "km/hr"
+    #   @api public
+    #   @return [String, nil] the unit of distance the vehicle displays
+    #   @example
+    #     gui_settings.distance_units
+    attribute :distance_units, :gui_distance_units
+
+    # @!method temperature_units
+    #   The unit of temperature the vehicle displays, "F" or "C"
+    #   @api public
+    #   @return [String, nil] the unit of temperature the vehicle displays
+    #   @example
+    #     gui_settings.temperature_units
+    attribute :temperature_units, :gui_temperature_units
+
+    # @!method charge_rate_units
+    #   The unit of charge rate the vehicle displays, such as "mi/hr" or "kW"
+    #   @api public
+    #   @return [String, nil] the unit of charge rate the vehicle displays
+    #   @example
+    #     gui_settings.charge_rate_units
+    attribute :charge_rate_units, :gui_charge_rate_units
+
+    # @!method range_display
+    #   The range the vehicle displays, "Rated" or "Ideal"
+    #   @api public
+    #   @return [String, nil] the range the vehicle displays
+    #   @example
+    #     gui_settings.range_display
+    attribute :range_display, :gui_range_display
+
+    # @!method twenty_four_hour_time?
+    #   Whether the vehicle displays the time on a 24-hour clock
+    #   @api public
+    #   @return [Boolean] whether the vehicle displays the time on a 24-hour clock
+    #   @example
+    #     gui_settings.twenty_four_hour_time?
+    predicate :twenty_four_hour_time, :gui_24_hour_time
+
+    # @!method timestamp
+    #   The time the vehicle reported the state
+    #   @api public
+    #   @return [Time, nil] the time the vehicle reported the state
+    #   @raise [InvalidResponse] if the timestamp is not a number of milliseconds
+    #   @example
+    #     gui_settings.timestamp
+    time_attribute :timestamp
+  end
+end

data/lib/tesla/idempotence.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Tesla
+  # Tells whether a request can be sent again, mixed into the client and the connection pool
+  #
+  # A safe request only asks the server for something, so sending it again leaves the vehicle as it was and is
+  # answered as the first one would have been. A request that asks a vehicle to do something, such as honking the
+  # horn or opening the trunk, is not safe: it cannot be sent a second time to find out whether the vehicle acted on
+  # the first one, so it is not sent again once it may have arrived (see {RetryHandler}).
+  #
+  # @api private
+  module Idempotence
+    # The HTTP methods that ask the server for something rather than asking it to do something
+    SAFE_METHODS = %w[GET HEAD OPTIONS TRACE].freeze
+
+    private
+
+    # Whether a request made with an HTTP method only asks the server for something
+    #
+    # The method is named rather than the request, so that a caller deciding whether to send a request again does
+    # not have to have built one (see {Client#execute_request}).
+    #
+    # @api private
+    # @param http_method [String, Symbol] the HTTP method, in either case
+    # @return [Boolean] whether a request made with the method is safe
+    def safe?(http_method)
+      SAFE_METHODS.include?(http_method.to_s.upcase)
+    end
+  end
+end

data/lib/tesla/identifiers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "vehicle"
+
+module Tesla
+  # Resolves identifiers from resource objects, so API methods accept either
+  #
+  # @api private
+  module Identifiers
+    private
+
+    # Resolve the tag the Fleet API knows a vehicle by from a tag or a vehicle
+    #
+    # A vehicle is known by its VIN or by its ID. The VIN is preferred for a vehicle that carries both, since the
+    # vehicle command proxy knows a vehicle only by its VIN.
+    #
+    # @api private
+    # @param vehicle [String, Integer, Vehicle] a VIN, the ID of a vehicle, or a vehicle
+    # @return [String, Integer, nil] the VIN or the ID
+    def tag_of(vehicle)
+      case vehicle
+      when Vehicle then vehicle.vin || vehicle.id
+      else vehicle
+      end
+    end
+  end
+end