tesla 0.0.1 → 0.1.0

data/lib/tesla/vehicle_config.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Tesla
+  # The configuration a vehicle was built with
+  # @api public
+  class VehicleConfig < Resource
+    inspect_with :car_type, :trim_badging
+
+    # @!method car_type
+    #   The model of the vehicle, such as "model3" or "modely"
+    #   @api public
+    #   @return [String, nil] the model of the vehicle
+    #   @example
+    #     vehicle_config.car_type
+    attribute :car_type
+
+    # @!method trim_badging
+    #   The trim of the vehicle, such as "p90d"
+    #   @api public
+    #   @return [String, nil] the trim of the vehicle
+    #   @example
+    #     vehicle_config.trim_badging
+    attribute :trim_badging
+
+    # @!method exterior_color
+    #   The color of the paint
+    #   @api public
+    #   @return [String, nil] the color of the paint
+    #   @example
+    #     vehicle_config.exterior_color
+    attribute :exterior_color
+
+    # @!method wheel_type
+    #   The wheels the vehicle was built with
+    #   @api public
+    #   @return [String, nil] the wheels the vehicle was built with
+    #   @example
+    #     vehicle_config.wheel_type
+    attribute :wheel_type
+
+    # @!method charge_port_type
+    #   The type of the charge port, such as "US" or "CCS"
+    #   @api public
+    #   @return [String, nil] the type of the charge port
+    #   @example
+    #     vehicle_config.charge_port_type
+    attribute :charge_port_type
+
+    # @!method sun_roof_installed
+    #   The sunroof the vehicle was built with, or zero for none
+    #   @api public
+    #   @return [Integer, nil] the sunroof the vehicle was built with
+    #   @example
+    #     vehicle_config.sun_roof_installed
+    attribute :sun_roof_installed
+
+    # @!method can_actuate_trunks?
+    #   Whether the trunks of the vehicle can be opened remotely
+    #   @api public
+    #   @return [Boolean] whether the trunks of the vehicle can be opened remotely
+    #   @example
+    #     vehicle_config.can_actuate_trunks?
+    predicate :can_actuate_trunks
+
+    # @!method power_liftgate?
+    #   Whether the vehicle has a powered liftgate
+    #
+    #   A powered liftgate can be closed as well as opened remotely.
+    #
+    #   @api public
+    #   @return [Boolean] whether the vehicle has a powered liftgate
+    #   @example
+    #     vehicle_config.power_liftgate?
+    predicate :power_liftgate, :plg
+
+    # @!method right_hand_drive?
+    #   Whether the vehicle is right-hand drive
+    #   @api public
+    #   @return [Boolean] whether the vehicle is right-hand drive
+    #   @example
+    #     vehicle_config.right_hand_drive?
+    predicate :right_hand_drive, :rhd
+
+    # @!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
+    #     vehicle_config.timestamp
+    time_attribute :timestamp
+  end
+end

data/lib/tesla/vehicle_data.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "charge_state"
+require_relative "climate_state"
+require_relative "drive_state"
+require_relative "gui_settings"
+require_relative "vehicle"
+require_relative "vehicle_config"
+require_relative "vehicle_state"
+
+module Tesla
+  # A vehicle and the state of its subsystems
+  #
+  # The Fleet API answers with the states it was asked for, so the reader of one it was not asked for answers nil
+  # (see {API::VehicleEndpoints#vehicle_data}).
+  #
+  # @api public
+  class VehicleData < Vehicle
+    # @!method charge_state
+    #   The state of the battery and the charging
+    #   @api public
+    #   @return [ChargeState, nil] the state of the battery and the charging
+    #   @example
+    #     vehicle_data.charge_state.battery_level
+    resource_attribute :charge_state, ChargeState
+
+    # @!method climate_state
+    #   The state of the climate control
+    #   @api public
+    #   @return [ClimateState, nil] the state of the climate control
+    #   @example
+    #     vehicle_data.climate_state.inside_temp
+    resource_attribute :climate_state, ClimateState
+
+    # @!method drive_state
+    #   The position and the driving state
+    #   @api public
+    #   @return [DriveState, nil] the position and the driving state
+    #   @example
+    #     vehicle_data.drive_state.shift_state
+    resource_attribute :drive_state, DriveState
+
+    # @!method gui_settings
+    #   The units and formats the vehicle displays
+    #   @api public
+    #   @return [GUISettings, nil] the units and formats the vehicle displays
+    #   @example
+    #     vehicle_data.gui_settings.temperature_units
+    resource_attribute :gui_settings, GUISettings
+
+    # @!method vehicle_config
+    #   The configuration the vehicle was built with
+    #   @api public
+    #   @return [VehicleConfig, nil] the configuration the vehicle was built with
+    #   @example
+    #     vehicle_data.vehicle_config.car_type
+    resource_attribute :vehicle_config, VehicleConfig
+
+    # @!method vehicle_state
+    #   The physical state of the vehicle
+    #   @api public
+    #   @return [VehicleState, nil] the physical state of the vehicle
+    #   @example
+    #     vehicle_data.vehicle_state.locked?
+    resource_attribute :vehicle_state, VehicleState
+  end
+end

data/lib/tesla/vehicle_state.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Tesla
+  # The physical state of a vehicle, such as whether it is locked
+  # @api public
+  class VehicleState < Resource
+    inspect_with :car_version, :odometer
+
+    # @!method car_version
+    #   The version of the software the vehicle runs
+    #   @api public
+    #   @return [String, nil] the version of the software the vehicle runs
+    #   @example
+    #     vehicle_state.car_version
+    attribute :car_version
+
+    # @!method odometer
+    #   The odometer in miles, whatever unit the vehicle displays
+    #   @api public
+    #   @return [Float, nil] the odometer
+    #   @example
+    #     vehicle_state.odometer
+    attribute :odometer
+
+    # @!method vehicle_name
+    #   The name the owner gave the vehicle
+    #   @api public
+    #   @return [String, nil] the name the owner gave the vehicle
+    #   @example
+    #     vehicle_state.vehicle_name
+    attribute :vehicle_name
+
+    # @!method sun_roof_state
+    #   The state of the sunroof, such as "closed" or "vent"
+    #   @api public
+    #   @return [String, nil] the state of the sunroof
+    #   @example
+    #     vehicle_state.sun_roof_state
+    attribute :sun_roof_state
+
+    # @!method locked?
+    #   Whether the vehicle is locked
+    #   @api public
+    #   @return [Boolean] whether the vehicle is locked
+    #   @example
+    #     vehicle_state.locked?
+    predicate :locked
+
+    # @!method sentry_mode?
+    #   Whether Sentry Mode is on
+    #   @api public
+    #   @return [Boolean] whether Sentry Mode is on
+    #   @example
+    #     vehicle_state.sentry_mode?
+    predicate :sentry_mode
+
+    # @!method valet_mode?
+    #   Whether Valet Mode is on
+    #   @api public
+    #   @return [Boolean] whether Valet Mode is on
+    #   @example
+    #     vehicle_state.valet_mode?
+    predicate :valet_mode
+
+    # @!method user_present?
+    #   Whether someone is in the vehicle
+    #   @api public
+    #   @return [Boolean] whether someone is in the vehicle
+    #   @example
+    #     vehicle_state.user_present?
+    predicate :user_present, :is_user_present
+
+    # @!method remote_start?
+    #   Whether the vehicle has been started remotely
+    #   @api public
+    #   @return [Boolean] whether the vehicle has been started remotely
+    #   @example
+    #     vehicle_state.remote_start?
+    predicate :remote_start
+
+    # @!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
+    #     vehicle_state.timestamp
+    time_attribute :timestamp
+
+    # Whether the front trunk is open
+    #
+    # @api public
+    # @return [Boolean] whether the front trunk is open
+    # @example
+    #   vehicle_state.frunk_open?
+    def frunk_open?
+      open?(self[:ft])
+    end
+
+    # Whether the rear trunk is open
+    #
+    # @api public
+    # @return [Boolean] whether the rear trunk is open
+    # @example
+    #   vehicle_state.trunk_open?
+    def trunk_open?
+      open?(self[:rt])
+    end
+
+    private
+
+    # Whether a closure is open
+    #
+    # The Fleet API writes an open closure as a number other than zero.
+    #
+    # @api private
+    # @param value [Integer, nil] the state of the closure
+    # @return [Boolean] whether the closure is open, which one the response does not carry is not
+    def open?(value)
+      !(value.nil? || value.zero?)
+    end
+  end
+end

data/lib/tesla/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Tesla
+  # The current version of the Tesla gem
+  VERSION = "0.1.0"
+end

data/lib/tesla.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require_relative "tesla/client"
+require_relative "tesla/configuration"
+require_relative "tesla/version"
+
+# A Ruby wrapper for the Tesla Fleet API
+#
+# Every public method of {API} is a method of this module too, delegated to {.client}: {API::VehicleEndpoints#vehicles}
+# is `Tesla.vehicles`, {API::ClosureEndpoints#actuate_trunk} is `Tesla.actuate_trunk`, and so on for every endpoint.
+# They are delegated as the module is loaded rather than written out, so they are not listed among the methods
+# below; {API} groups them into one mixin per topic, and each is documented there.
+#
+# The raw request methods, {Client#get} and the rest, are on the client rather than on this module, since a request
+# of your own is made with {.client}.
+#
+# @api public
+# @see API The endpoints, grouped into one mixin per topic
+module Tesla
+  extend Configuration
+  extend SingleForwardable
+
+  # The mutex that guards the client the API methods of the module delegate to
+  CLIENT_MUTEX = Mutex.new
+  private_constant :CLIENT_MUTEX
+
+  # The settings of the global configuration a client is built from, and built again for when one of them changes
+  CLIENT_SETTINGS = %i[host access_token refresh_token client_id client_secret].freeze
+  private_constant :CLIENT_SETTINGS
+
+  # The settings of the global configuration that are applied to the client the module has, rather than building
+  # another one from them
+  APPLIED_SETTINGS = %i[redirect_uri audience authorization_endpoint token_endpoint on_token_refresh user_agent
+    open_timeout read_timeout write_timeout keep_alive_timeout debug_output proxy_url ca_file max_redirects
+    max_retries max_retry_delay].freeze
+  private_constant :APPLIED_SETTINGS
+
+  # @!method self.new(**options)
+  #   Alias for Tesla::Client.new
+  #   @api public
+  #   @param options [Hash] options passed to {Tesla::Client#initialize}
+  #   @yield [client] the client, which is closed once the block is done with it (see {Tesla::Client.new})
+  #   @return [Tesla::Client, Object] a new client, or what the block returned
+  #   @example Create a client
+  #     Tesla.new(access_token: "eyJhbGciOiJSUzI1NiIs")
+  #   @example Close the connections of a client once a block is done with it
+  #     Tesla.new { |client| client.vehicles }
+  def_delegator "Tesla::Client", :new
+
+  # The endpoints of {API}, each delegated to the client the module has. They are read from the module as it is
+  # loaded rather than written out one by one, so YARD has none of them to document here; {API} documents each of
+  # them in the mixin it belongs to.
+  def_delegators :client, *API.public_instance_methods
+
+  # The methods of SingleForwardable, which the module delegates with rather than offers, so that `Tesla.delegate`
+  # and the rest are not mistaken for methods of the API
+  private_class_method(*SingleForwardable.instance_methods)
+
+  # The client the API methods of the module delegate to
+  #
+  # The client is built from the global configuration, and a change to that configuration is applied to the client
+  # it has rather than building another one, which would throw away what the client learned: the tokens it was
+  # answered with when it refreshed its access token, of which the refresh token is the only one that still works.
+  #
+  # Another client is built only for the host and the credentials that tokens are issued for, since a client that
+  # was given other ones has nothing to keep from the ones it had.
+  #
+  # @api public
+  # @return [Client] the client
+  # @example Perform a raw request with the module's client
+  #   Tesla.client.get("/api/1/vehicles")
+  def self.client
+    CLIENT_MUTEX.synchronize do
+      rebuild_client unless values_of(CLIENT_SETTINGS).eql?(@client_values)
+      apply_settings unless values_of(APPLIED_SETTINGS).eql?(@applied_values)
+      @client
+    end
+  end
+
+  # Reset the global configuration and forget the client
+  #
+  # The client is forgotten as well as the configuration it was built from, so that what it learned from
+  # credentials that have been reset, such as the tokens it refreshed, is not kept. Its connections are closed,
+  # since no request of the module will be sent on them again.
+  #
+  # The configuration is reset while the client is forgotten rather than afterwards, so that a thread asking for the
+  # client is given one built from the configuration as it was or as it has been reset, rather than one built from a
+  # configuration that is half of each.
+  #
+  # @api public
+  # @return [self]
+  # @example Reset the configuration
+  #   Tesla.reset
+  def self.reset
+    CLIENT_MUTEX.synchronize do
+      @client&.close
+      @client_values = nil
+      super
+    end
+  end
+
+  # Build the client again from the global configuration
+  #
+  # The client is built from the whole of the configuration, so the settings that are applied to a client are the
+  # ones it already has. The client being replaced is closed once the new one has been built, since no request of
+  # the module will be sent on its connections again, and so that a configuration a client cannot be built from
+  # leaves the client the module has open rather than closing it on the way to raising.
+  #
+  # @api private
+  # @return [Array<Object>] the settings the client was built from
+  def self.rebuild_client
+    client = new
+    @client&.close
+    @client = client
+    @client_values = values_of(CLIENT_SETTINGS)
+  end
+  private_class_method :rebuild_client
+
+  # The values of settings of the global configuration
+  #
+  # @api private
+  # @param settings [Array<Symbol>] the names of the settings
+  # @return [Array<Object>] the values
+  def self.values_of(settings)
+    settings.map { |setting| public_send(setting) }
+  end
+  private_class_method :values_of
+
+  # Apply the rest of the global configuration to the client the module has
+  #
+  # @api private
+  # @return [Array<Object>] the configuration applied to the client
+  def self.apply_settings
+    APPLIED_SETTINGS.each { |setting| @client.public_send(:"#{setting}=", public_send(setting)) }
+    @applied_values = values_of(APPLIED_SETTINGS)
+  end
+  private_class_method :apply_settings
+end

data/sig/manifest.yaml

@@ -0,0 +1,10 @@
+# The standard libraries the signatures of tesla refer to, which rbs collection loads for code that depends on it
+dependencies:
+  - name: forwardable
+  - name: json
+  - name: net-http
+  - name: openssl
+  - name: time
+  - name: timeout
+  - name: uri
+  - name: zlib