smartcar 0.0.0 → 1.0.3

data/lib/smartcar/base.rb

@@ -0,0 +1,72 @@
+require 'oauth2'
+require 'base64'
+module Smartcar
+  # The Base class for all of the other class.
+  # Let other classes inherit from here and put common methods here.
+  class Base
+    include Utils
+
+    # Error raised when an invalid parameter is passed.
+    class InvalidParameterValue < StandardError; end
+    # Constant for Bearer auth type
+    BEARER = 'BEARER'.freeze
+    # Constant for Basic auth type
+    BASIC = 'BASIC'.freeze
+
+    attr_accessor :token, :error, :meta
+
+    %i{get post patch put delete}.each do |verb|
+      # meta programming and define all Restful methods.
+      # @param path [String] the path to hit for the request.
+      # @param data [Hash] request body if needed.
+      #
+      # @return [Hash] The response Json parsed as a hash.
+      define_method verb do |path, data=nil|
+        response = service.send(verb) do |request|
+          request.headers['Authorization'] = "BEARER #{token}"
+          request.headers['Authorization'] = "BASIC #{get_basic_auth}" if data[:auth] == BASIC
+          request.headers['sc-unit-system'] = unit_system
+          request.headers['Content-Type'] = "application/json"
+          complete_path = "/#{API_VERSION}#{path}"
+          if verb==:get
+            request.url complete_path, data
+          else
+            request.url complete_path
+            request.body = data.to_json if data
+          end
+        end
+        error = get_error(response)
+        raise error if error
+        [JSON.parse(response.body), response.headers]
+      end
+    end
+
+    # This requires a proc 'PATH' to be defined in the class
+    # @param path [String] resource path
+    # @param options [Hash] query params
+    # @param auth [String] type of auth
+    #
+    # @return [Object]
+    def fetch(path: , options: {}, auth: 'BEARER')
+      _path = path
+      _path += "?#{URI.encode_www_form(options)}" unless options.empty?
+      get(_path, {auth: auth})
+    end
+
+    private
+
+    # returns auth token for BASIC auth
+    #
+    # @return [String] Base64 encoding of CLIENT:SECRET
+    def get_basic_auth
+      Base64.strict_encode64("#{get_config('CLIENT_ID')}:#{get_config('CLIENT_SECRET')}")
+    end
+
+    # gets a smartcar API service/client
+    #
+    # @return [OAuth2::AccessToken] An initialized AccessToken instance that acts as service client
+    def service
+      @service ||= Faraday.new(url: SITE)
+    end
+  end
+end

data/lib/smartcar/battery.rb

@@ -0,0 +1,13 @@
+module Smartcar
+  # class to represent Battery info
+  #@attr [Number] percentRemaining Decimal value representing the remaining charge percent.
+  #@attr [Number] range Remaining range of the vehicle.
+  class Battery < Base
+    # Path Proc for hitting battery end point
+    PATH = Proc.new{|id| "/vehicles/#{id}/battery"}
+    attr_reader :percentRemaining, :range
+
+    # just to have Ruby-esque method names
+    alias_method :percentage_remaining, :percentRemaining
+  end
+end

data/lib/smartcar/charge.rb

@@ -0,0 +1,13 @@
+module Smartcar
+  # class to represent Charge info
+  #@attr [Boolean] isPluggedIn Specifies if the vehicle is plugged in.
+  #@attr [String] state Charging state of the vehicle.
+  class Charge < Base
+    # Path Proc for hitting charge end point
+    PATH = Proc.new{|id| "/vehicles/#{id}/charge"}
+    attr_reader :isPluggedIn, :state
+
+    # just to have Ruby-esque method names
+    alias_method :is_plugged_in?, :isPluggedIn
+  end
+end

data/lib/smartcar/engine_oil.rb

@@ -0,0 +1,12 @@
+module Smartcar
+  # class to represent Engine oil info
+  #@attr [Number] lifeRemaining Remaining life of the engine oil
+  class EngineOil < Base
+    # Path Proc for hitting engine oil end point
+    PATH = Proc.new{|id| "/vehicles/#{id}/engine/oil"}
+    attr_reader :lifeRemaining
+
+    # just to have Ruby-esque method names
+    alias_method :life_remaining, :lifeRemaining
+  end
+end

data/lib/smartcar/fuel.rb

@@ -0,0 +1,15 @@
+module Smartcar
+  # class to represent Fuel info
+  #@attr [Number] amountRemaining Amount of fuel remaining.
+  #@attr [Number] percentageRemaining Decimal value representing the remaining fuel percent.
+  #@attr [Number] range Remaining range of the vehicle.
+  class Fuel < Base
+    # Path Proc for hitting fuel end point
+    PATH = Proc.new{|id| "/vehicles/#{id}/fuel"}
+    attr_reader :amountRemaining, :percentRemaining, :range
+
+    # just to have Ruby-esque method names
+    alias_method :amount_remaining, :amountRemaining
+    alias_method :percent_remaining, :percentRemaining
+  end
+end

data/lib/smartcar/location.rb

@@ -0,0 +1,10 @@
+module Smartcar
+  # class to represent Location info
+  #@attr [Number] latitude Latitude of last recorded location.
+  #@attr [Number] longitude Longitude of last recorded location.
+  class Location < Base
+    # Path Proc for hitting location end point
+    PATH = Proc.new{|id| "/vehicles/#{id}/location"}
+    attr_reader :latitude, :longitude
+  end
+end

data/lib/smartcar/oauth.rb

@@ -0,0 +1,91 @@
+module Smartcar
+  # Oauth class to take care of the Oauth 2.0 with Smartcar APIs
+  #
+  class Oauth < Base
+    extend Utils
+    # By default users are not shown the permission dialog if they have already
+    # approved the set of scopes for this application. The application can elect
+    # to always display the permissions dialog to the user by setting
+    # approval_prompt to `force`.
+    #
+    # @param options [Hash]
+    # @option options[:client_id] [String] - Client ID, if not passed fallsback to ENV['CLIENT_ID']
+    # @option options[:client_secret] [String] - Client Secret, if not passed fallsback to ENV['CLIENT_SECRET']
+    # @option options[:redirect_uri] [String] - Redirect URI, if not passed fallsback to ENV['REDIRECT_URI']
+    # @option options[:state] [String] - OAuth state parameter passed to the
+    # redirect uri. This parameter may be used for identifying the user who
+    # initiated the request.
+    # @option options[:test_mode] [Boolean] - Setting this to 'true' runs it in test mode.
+    # @option options[:force_prompt] [Boolean] - Setting `force_prompt` to
+    # `true` will show the permissions approval screen on every authentication
+    # attempt, even if the user has previously consented to the exact scope of
+    # permissions.
+    # @option options[:make] [String] - `make' is an optional parameter that allows
+    # users to bypass the car brand selection screen.
+    # For a complete list of supported makes, please see our
+    # [API Reference](https://smartcar.com/docs/api#authorization) documentation.
+    # @option options[:scope] [Array of Strings] - array of scopes that specify what the user can access
+    #   EXAMPLE : ['read_odometer', 'read_vehicle_info', 'required:read_location']
+    # For further details refer to https://smartcar.com/docs/guides/scope/
+    #
+    # @return [Smartcar::Oauth] Returns a Smartcar::Oauth Object that has other methods
+    def initialize(options)
+      @redirect_uri = options[:redirect_uri] || get_config('REDIRECT_URI')
+      @client_id = options[:client_id] || get_config('CLIENT_ID')
+      @client_secret = options[:client_secret] || get_config('CLIENT_SECRET')
+
+      @auth_parameters = {
+        redirect_uri: @redirect_uri,
+        approval_prompt: options[:force_prompt] ? FORCE : AUTO,
+        mode: options[:test_mode] ? TEST : LIVE,
+        response_type: CODE
+      }
+      @auth_parameters[:scope] = options[:scope].join(' ') if options[:scope]
+      %I(state make).each do |parameter|
+        parameters[:parameter] = options[:parameter] unless options[:parameter].nil?
+      end
+    end
+
+    # Generate the OAuth authorization URL.
+    #
+    # @return [String] Authorization URL string
+    def authorization_url
+      client.auth_code.authorize_url(@auth_parameters)
+    end
+
+    # Generates the tokens hash using the code returned in oauth process.
+    # @param auth_code [String] This is the code that is returned after user
+    # visits and authorizes on the authorization URL.
+    #
+    # @return [Hash] Hash of token, refresh token, expiry info and token type
+    def get_token(auth_code)
+      client.auth_code
+        .get_token(
+          auth_code,
+          redirect_uri: @redirect_uri
+        ).to_hash
+    end
+
+    # Refreshing the access token
+    # @param token_hash [Hash] This is the hash that is returned with the
+    # get_token method
+    #
+    # @return [Hash] Hash of token, refresh token, expiry info and token type
+    def refresh_token(token_hash)
+      token_object = OAuth2::AccessToken.from_hash(client, token_hash)
+      token_object = token_object.refresh!
+      token_object.to_hash
+    end
+
+    private
+    # gets the Oauth Client object
+    #
+    # @return [OAuth2::Client] A Oauth Client object.
+    def client
+      @client ||= OAuth2::Client.new( @client_id,
+        @client_secret,
+        :site => OAUTH_PATH
+      )
+    end
+  end
+end

data/lib/smartcar/odometer.rb

@@ -0,0 +1,9 @@
+module Smartcar
+  # class to represent Odometer
+  #@attr [Number] distanceLast recorded odometer reading.
+  class Odometer < Base
+    # Path Proc for hitting odometer end point
+    PATH = Proc.new{|id| "/vehicles/#{id}/odometer"}
+    attr_reader :distance
+  end
+end

data/lib/smartcar/permissions.rb

@@ -0,0 +1,9 @@
+module Smartcar
+  # class to represent permissions response
+  #@attr [Array] permissions Array of permissions granted on the vehicle.
+  class Permissions < Base
+    # Path Proc for hitting permissions end point
+    PATH = Proc.new{|id| "/vehicles/#{id}/permissions"}
+    attr_reader :permissions
+  end
+end

data/lib/smartcar/tire_pressure.rb

@@ -0,0 +1,19 @@
+module Smartcar
+  # class to represent Tire Pressure response
+  #@attr [Number] back_left Last recorded tire pressure of the back left tire.
+  #@attr [Number] back_right Last recorded tire pressure of the back right tire.
+  #@attr [Number] front_left Last recorded tire pressure of the front left tire.
+  #@attr [Number] front_right Last recorded tire pressure of the front right tire.
+
+  class TirePressure < Base
+    # Path Proc for hitting tire pressure end point
+    PATH = Proc.new{|id| "/vehicles/#{id}/tires/pressure"}
+    attr_reader :backLeft, :backRight, :frontLeft, :frontRight
+
+    # just to have Ruby-esque method names
+    alias_method :back_left, :backLeft
+    alias_method :back_right, :backRight
+    alias_method :front_left, :frontLeft
+    alias_method :front_right, :frontRight
+  end
+end

data/lib/smartcar/user.rb

@@ -0,0 +1,26 @@
+module Smartcar
+  # Class to get to user API.
+  #@attr [String] id Smartcar user id.
+  #@attr [String] token Access token used to connect to Smartcar API.
+  class User < Base
+    # Path  for hitting user end point
+    USER_PATH = '/user'.freeze
+    attr_reader :id, :token
+
+    def initialize(token:)
+      raise InvalidParameterValue.new, "Access Token(token) is a required field" if token.nil?
+      @token = token
+    end
+
+    # Class method Used to get user id
+    # EX : Smartcar::User.fetch
+    # API - https://smartcar.com/docs/api#get-user
+    # @param token [String] Access token
+    #
+    # @return [User] object
+    def self.user_id(token:)
+      new(token: token).get(USER_PATH)['id']
+    end
+
+  end
+end

data/lib/smartcar/utils.rb

@@ -0,0 +1,35 @@
+  # Utils module , provides utility methods to underlying classes
+  module Utils
+  # A constructor to take a hash and assign it to the instance variables
+  # @param options = {} [Hash] Could by any class's hash, but the first level keys should be defined in the class
+  #
+  # @return [Subclass os Base] Returns object of any subclass like Report
+  def initialize(options = {})
+    options.each do |attribute, value|
+      instance_variable_set("@#{attribute}", value)
+    end
+  end
+
+  # gets a given env variable, checks for existence and throws exception if not present
+  # @param config_name [String] key of the env variable
+  #
+  # @return [String] value of the env variable
+  def get_config(config_name)
+    config_name = "INTEGRATION_#{config_name}" if ENV['MODE'] == 'test'
+    raise Smartcar::ConfigNotFound, "Environment variable #{config_name} not found !" unless ENV[config_name]
+    ENV[config_name]
+  end
+
+  # Given the response from smartcar API, returns an error object if needed
+  # @param response [Object] response Object with status and body
+  #
+  # @return [Object] nil OR Error object
+  def get_error(response)
+    status = response.status
+    return nil if [200,204].include?(status)
+    return Smartcar::ServiceUnavailableError.new("Service Unavailable - #{response.body}") if status == 404
+    return Smartcar::BadRequestError.new("Bad Request - #{response.body}") if status == 400
+    return Smartcar::AuthenticationError.new("Authentication error") if status == 401
+    return Smartcar::ExternalServiceError.new("API error - #{response.body}")
+  end
+end

data/lib/smartcar/vehicle.rb

@@ -0,0 +1,294 @@
+module Smartcar
+  # Vehicle class to connect to vehicle basic info,disconnect, lock unlock and get all vehicles API
+  # For ease of use, this also has methods define to be able to call other resources on a vehicle object
+  # For Ex. Vehicle object will be treate as an entity and doing vehicle_object.
+  # Battery should return Battery object.
+  #
+  #@attr [String] token Access token used to connect to Smartcar API.
+  #@attr [String] id Smartcar vehicle ID.
+  #@attr [String] unit_system unit system to represent the data in.
+  class Vehicle < Base
+    include Utils
+
+
+    # Path for hitting compatibility end point
+    COMPATIBLITY_PATH = '/compatibility'.freeze
+
+    # Path for hitting vehicle ids end point
+    PATH = Proc.new{|id| "/vehicles/#{id}"}
+
+    attr_reader :id
+    attr_accessor :token, :unit_system
+
+    def initialize(token:, id:, unit_system: IMPERIAL)
+      raise InvalidParameterValue.new, "Invalid Units provided : #{unit_system}" unless UNITS.include?(unit_system)
+      raise InvalidParameterValue.new, "Vehicle ID (id) is a required field" if id.nil?
+      raise InvalidParameterValue.new, "Access Token(token) is a required field" if token.nil?
+      @token = token
+      @id = id
+      @unit_system = unit_system
+    end
+
+    # Class method Used to get all the vehicles in the app. This only returns
+    # API - https://smartcar.com/docs/api#get-all-vehicles
+    # @param token [String] - Access token
+    # @param options [Hash] - Optional filter parameters (check documentation)
+    #
+    # @return [Array] of vehicle IDs(Strings)
+    def self.all_vehicle_ids(token:, options: {})
+      response, meta = new(token: token, id: 'none').fetch(
+        path: PATH.call(''),
+        options: options
+      )
+      response['vehicles']
+    end
+
+    # Class method Used to check compatiblity for VIN and scope
+    # API - https://smartcar.com/docs/api#connect-compatibility
+    # @param vin [String] VIN of the vehicle to be checked
+    # @param scope [Array of Strings] - array of scopes
+    #
+    # @return [Boolean] true or false
+    def self.compatible?(vin:, scope:)
+      raise InvalidParameterValue.new, "vin is a required field" if vin.nil?
+      raise InvalidParameterValue.new, "scope is a required field" if scope.nil?
+
+      response, meta = new(token: 'none', id: 'none').fetch(path: COMPATIBLITY_PATH,
+        options: {
+          vin: vin,
+          scope: scope.join(' ')
+        },
+        auth: BASIC
+      )
+      response['compatible']
+    end
+
+    # Method to get batch requests
+    # API - https://smartcar.com/docs/api#post-batch-request
+    # @param attributes [Array] Array of strings or symbols of attributes to be fetched together
+    #
+    # @return [Hash] Hash wth key as requested attribute(symbol) and value as Error OR Object of the requested attribute
+    def batch(attributes = [])
+      raise InvalidParameterValue.new, "vin is a required field" if attributes.nil?
+      request_body = get_batch_request_body(attributes)
+      response, _meta = post(PATH.call(id) + "/batch", request_body)
+      process_batch_response(response)
+    end
+
+    # Fetch the list of permissions that this application has been granted for
+    # this vehicle
+    # EX : Smartcar::Vehicle.new(token: token, id: id).permissions
+    # @param options [Hash] - Optional filter parameters (check documentation)
+    #
+    # @return [Array] of permissions (Strings)
+    def permissions(options: {})
+      get_attribute(Permissions)
+    end
+
+    #  Method Used toRevoke access for the current requesting application
+    # API - https://smartcar.com/docs/api#delete-disconnect
+    #
+    # @return [Boolean] true if success
+    def disconnect!
+      response = delete(PATH.call(id) + "/application")
+      response['status'] == SUCCESS
+    end
+
+    # Methods Used to lock car
+    # API - https://smartcar.com/docs/api#post-security
+    #
+    # @return [Boolean] true if success
+    def lock!
+      lock_or_unlock!(action: Smartcar::LOCK)
+    end
+
+    # Methods Used to unlock car
+    # API - https://smartcar.com/docs/api#post-security
+    #
+    # @return [Boolean] true if success
+    def unlock!
+      lock_or_unlock!(action: Smartcar::UNLOCK)
+    end
+
+    # Method used to start charging a car
+    #
+    #
+    # @return [Boolean] true if success
+    def start_charge!
+      start_or_stop_charge!(action: Smartcar::START_CHARGE)
+    end
+
+    # Method used to stop charging a car
+    #
+    #
+    # @return [Boolean] true if success
+    def stop_charge!
+      start_or_stop_charge!(action: Smartcar::STOP_CHARGE)
+    end
+
+    # Returns make model year and id of the vehicle
+    # API - https://smartcar.com/api#get-vehicle-attributes
+    #
+    # @return [VehicleAttributes] object
+    def vehicle_attributes
+      get_attribute(VehicleAttributes)
+    end
+
+    # Returns the state of charge (SOC) and remaining range of an electric or
+    # plug-in hybrid vehicle's battery.
+    # API - https://smartcar.com/docs/api#get-ev-battery
+    #
+    # @return [Battery] object
+    def battery
+      get_attribute(Battery)
+    end
+
+    # Returns the current charge status of the vehicle.
+    # API - https://smartcar.com/docs/api#get-ev-battery
+    #
+    # @return [Charge] object
+    def charge
+      get_attribute(Charge)
+    end
+
+    # Returns the remaining life span of a vehicle's engine oil
+    # API - https://smartcar.com/docs/api#get-engine-oil-life
+    #
+    # @return [EngineOil] object
+    def engine_oil
+      get_attribute(EngineOil)
+    end
+
+    # Returns the status of the fuel remaining in the vehicle's gas tank.
+    # API - https://smartcar.com/docs/api#get-fuel-tank
+    #
+    # @return [Fuel] object
+    def fuel
+      get_attribute(Fuel)
+    end
+
+    # Returns the last known location of the vehicle in geographic coordinates.
+    # API - https://smartcar.com/docs/api#get-location
+    #
+    # @return [Location] object
+    def location
+      get_attribute(Location)
+    end
+
+    # Returns the vehicle's last known odometer reading.
+    # API - https://smartcar.com/docs/api#get-odometer
+    #
+    # @return [Odometer] object
+    def odometer
+      get_attribute(Odometer)
+    end
+
+    # Returns the air pressure of each of the vehicle's tires.
+    # API - https://smartcar.com/docs/api#get-tire-pressure
+    #
+    # @return [TirePressure] object
+    def tire_pressure
+      get_attribute(TirePressure)
+    end
+
+    # Returns the vehicle's manufacturer identifier (VIN).
+    # API - https://smartcar.com/docs/api#get-vin
+    #
+    # @return [String] Vin of the vehicle.
+    def vin
+      _object = get_attribute(Vin)
+      @vin ||= _object.vin
+    end
+
+    private
+
+    def allowed_attributes
+      @allowed_attributes ||= {
+        battery: get_path(Battery),
+        charge: get_path(Charge),
+        engine_oil: get_path(EngineOil),
+        fuel: get_path(Fuel),
+        location: get_path(Location),
+        odometer: get_path(Odometer),
+        permissions: get_path(Permissions),
+        tire_pressure: get_path(TirePressure),
+        vin: get_path(Vin),
+      }
+    end
+
+    def path_to_class
+      @path_to_class ||= {
+        get_path(Battery) => Battery,
+        get_path(Charge) => Charge,
+        get_path(EngineOil) => EngineOil,
+        get_path(Fuel) => Fuel,
+        get_path(Location) => Location,
+        get_path(Odometer) => Odometer,
+        get_path(Permissions) => Permissions,
+        get_path(TirePressure) => TirePressure,
+        get_path(Vin) => Vin,
+      }
+    end
+
+    # @private
+    BatchItemResponse = Struct.new(:body, :status, :headers) do
+      def body_with_meta
+        body.merge(meta: headers)
+      end
+    end
+
+    def get_batch_request_body(attributes)
+      attributes = validated_attributes(attributes)
+      requests = attributes.each_with_object([]) do |item, requests|
+        requests << { path: allowed_attributes[item] }
+      end
+      { requests: requests }
+    end
+
+    def process_batch_response(responses)
+      inverted_map = allowed_attributes.invert
+      responses["responses"].each_with_object({}) do |response, result|
+        item_response = BatchItemResponse.new(response["body"], response["code"], response["headers"])
+        error = get_error(item_response)
+        path = response["path"]
+        result[inverted_map[path]] = error || get_object(path_to_class[path], item_response.body_with_meta)
+      end
+    end
+
+    def validated_attributes(attributes)
+      attributes.map!(&:to_sym)
+      unsupported_attributes = (attributes - allowed_attributes.keys) || []
+      unless unsupported_attributes.empty?
+        message = "Unsupported attribute(s) requested in batch  - #{unsupported_attributes.join(',')}"
+        raise InvalidParameterValue.new, message
+      end
+      attributes
+    end
+
+    def get_attribute(klass)
+      body, meta =  fetch(
+        path: klass::PATH.call(id)
+      )
+      get_object(klass, body.merge(meta: meta))
+    end
+
+    def get_object(klass, data)
+      klass.new(data)
+    end
+
+    def get_path(klass)
+      path = klass::PATH.call(id)
+      path.split("/vehicles/#{id}").last
+    end
+
+    def lock_or_unlock!(action:)
+      response, meta = post(PATH.call(id) + "/security", { action: action })
+      response['status'] == SUCCESS
+    end
+
+    def start_or_stop_charge!(action:)
+      response, meta = post(PATH.call(id) + "/charge", { action: action })
+      response['status'] == SUCCESS
+    end
+  end
+end