smartcar 3.8.0 → 3.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd4fcc86e7eb35c94b63f0546a0cac9795b8c9413e91da0631ddc04658e8d928
-  data.tar.gz: 414d4999f1919ef259a9eaee0733e4e23bf60f29a53d667684c41142c88f3f91
+  metadata.gz: 516891931fbdcdde2425bfd191721725ac0461195f164be2f2dfe231412b2db1
+  data.tar.gz: 463981a1ae045345f3ed8aaeadaa894dea6bc2effe88ebed1500c90aeb94b22f
 SHA512:
-  metadata.gz: 94512a886faac4382679adb6c6dc23464095e749907caab77c30914993cb12b084e1ea2377df9767b7bc855a14691204afb517764afa95242c4bd27575ef1695
-  data.tar.gz: 4f1649632ff635bf6d6a806761b33c9fbd180f572ee31b30a5584971c3a3bcbe9407b3778a3d3acbcf9d22ff7ca3fd7aedad95975735ae3877bcb52f044613ee
+  metadata.gz: f5f916ff6589a296048636071fd0227ad0446078a8bdab9e34be8dbcef278f799b3c91369d5623be77a11efddf8781b4e07af77a36966fa46ebaa2c03310bd60
+  data.tar.gz: 7b8e0ebbf68942b14d29946039a10aa16b6de2f03d1d737b86a67245be4e53a656654857449716e0e69faf0a9289379257c3ff0f6b04fa21fc3c9c771cfa1e55

data/.buddy/cd.yml

@@ -0,0 +1,29 @@
+- pipeline: cd
+  name: CD
+  fail_on_prepare_env_warning: true
+  events:
+    - type: PUSH
+      refs:
+        - refs/heads/master
+  actions:
+    - action: semantic release
+      type: BUILD
+      shell: BASH
+      docker_image_name: library/ruby
+      docker_image_tag: 2.7
+      execute_commands:
+        - "set -e  # Exit immediately if a command exits with non-zero status"
+        - export GEM_NAME="smartcar"
+        - export GEMSPEC_FILE="ruby-sdk.gemspec"
+        - 'export GEM_HOST_API_KEY="${RUBYGEMSAPI_KEY}"'
+        - 'if [ "${BUDDY_EXECUTION_TAG}" != "" ] && [ "${BUDDY_EXECUTION_BRANCH}" == "master" ]; then'
+        - '  echo "Tagged commit on master branch detected, proceeding with deployment..."'
+        - "  gem install bundler -v 2.3.1"
+        - "  gem build ${GEMSPEC_FILE}"
+        - '  GEM_VERSION=$(ruby -e "require ''rubygems''; spec = Gem::Specification::load(''${GEMSPEC_FILE}''); puts spec.version")'
+        - '  echo "Publishing ${GEM_NAME} version ${GEM_VERSION} to RubyGems..."'
+        - '  gem push "${GEM_NAME}-${GEM_VERSION}.gem"'
+        - '  echo "Deployment to RubyGems completed successfully"'
+        - else
+        - '  echo "Skipping deployment: This is not a tagged commit on the master branch"'
+        - fi

data/.buddy/ci.yml

@@ -0,0 +1,69 @@
+- pipeline: ci
+  name: CI
+  events:
+    - type: PUSH
+      refs:
+        - refs/heads/*
+  fail_on_prepare_env_warning: true
+  actions:
+    - action: Run tests
+      type: BUILD
+      docker_image_name: library/ruby
+      docker_image_tag: 3.3
+      execute_commands:
+        - "# Set Firefox environment variables to help with headless operation"
+        - Xvfb :99 -screen 0 1280x1024x24 &
+        - export DISPLAY=:99.0
+        - export MOZ_HEADLESS=1
+        - export MOZ_NO_REMOTE=1
+        - "export PATH=${HOME}/firefox-latest/firefox:$PATH"
+        - firefox --version
+        - firefox &
+        - ""
+        - "export PATH=${HOME}/geckodriver:$PATH"
+        - geckodriver --version
+        - ""
+        - export BUNDLE_GEMFILE=$PWD/Gemfile
+        - gem install bundler -v 2.3.1
+        - "bundle install --jobs=3 --retry=3 --deployment --path=${BUNDLE_PATH:-vendor/bundle}"
+        - ""
+        - export MODE=test
+        - bundle exec rake
+      setup_commands:
+        - apt-get update
+        - apt-get install -y \
+        - '  libgtk-3-0 \'
+        - '  libasound2 \'
+        - '  libdbus-glib-1-2 \'
+        - '  libx11-xcb1 \'
+        - '  libxt6 \'
+        - '  libnss3 \'
+        - '  libxtst6 \'
+        - '  libxss1 \'
+        - '  libpci3 \'
+        - '  libatk1.0-0 \'
+        - '  libatk-bridge2.0-0 \'
+        - '  libcups2 \'
+        - '  libdrm2 \'
+        - '  libxcomposite1 \'
+        - '  libxdamage1 \'
+        - '  libxfixes3 \'
+        - '  libxkbcommon0 \'
+        - '  libxrandr2 \'
+        - "  xvfb"
+        - ""
+        - ""
+        - "# Download the latest Firefox"
+        - wget -O /tmp/firefox-latest.tar.xz 'https://download.mozilla.org/?product=firefox-latest&lang=en-US&os=linux64'
+        - "mkdir -p ${HOME}/firefox-latest"
+        - "tar -xJf /tmp/firefox-latest.tar.xz -C ${HOME}/firefox-latest"
+        - ""
+        - "# Download Geckodriver"
+        - wget -O /tmp/geckodriver.tar.xz 'https://github.com/mozilla/geckodriver/releases/download/v0.26.0/geckodriver-v0.26.0-linux64.tar.gz'
+        - "mkdir -p ${HOME}/geckodriver"
+        - "tar -xzf /tmp/geckodriver.tar.xz -C ${HOME}/geckodriver"
+      services:
+        - type: SELENIUM_FIREFOX
+          connection:
+            host: selenium-ff
+      shell: BASH

data/.rubocop.yml

@@ -48,3 +48,8 @@ Metrics/CyclomaticComplexity:
 
 Metrics/PerceivedComplexity:
   Max: 10
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'lib/smartcar_error.rb'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    smartcar (3.8.0)
+    smartcar (3.9.5)
       oauth2 (~> 1.4)
       recursive-open-struct (~> 1.1.3)
 

data/Rakefile

@@ -3,7 +3,9 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:spec) do |t, args|
+  t.pattern = args.extras.join(' ') unless args.extras.empty?
+end
 
 require 'rubocop/rake_task'
 

data/lib/smartcar/auth_client.rb

@@ -13,14 +13,16 @@ module Smartcar
     # @param [Hash] options
     # @option options[:client_id] [String] - Client ID, if not passed fallsback to ENV['SMARTCAR_CLIENT_ID']
     # @option options[:client_secret] [String] - Client Secret, if not passed fallsback to ENV['SMARTCAR_CLIENT_SECRET']
-    # @option options[:redirect_uri] [String] - Redirect URI, if not passed fallsback to ENV['SMARTCAR_REDIRECT_URI']
+    # @option options[:redirect_uri] [String] - Redirect URI registered in the
+    # application settings. The given URL must exactly match one of the registered URLs.
+    # This parameter is optional and should normally be set within the Smartcar Dashboard.
     # @option options[:test_mode] [Boolean] - [DEPRECATED], please use `mode` instead.
     # Launch Smartcar Connect in [test mode](https://smartcar.com/docs/guides/testing/).
     # @option options[:mode] [String] - Determine what mode Smartcar Connect should be launched in.
     # Should be one of test, live or simulated.
     # @return [Smartcar::AuthClient] Returns a Smartcar::AuthClient Object that has other methods
     def initialize(options)
-      options[:redirect_uri] ||= get_config('SMARTCAR_REDIRECT_URI')
+      options[:redirect_uri] ||= get_config('SMARTCAR_REDIRECT_URI', { nullable: true })
       options[:client_id] ||= get_config('SMARTCAR_CLIENT_ID')
       options[:client_secret] ||= get_config('SMARTCAR_CLIENT_SECRET')
       options[:auth_origin] = ENV['SMARTCAR_AUTH_ORIGIN'] || AUTH_ORIGIN
@@ -30,9 +32,11 @@ module Smartcar
     end
 
     # Generate the OAuth authorization URL.
-    # @param scope [Array<String>] Array of permissions that specify what the user can access
+    # @param scope_or_options [Array<String>, Hash] Array of permissions 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/
+    #   For further details refer to https://smartcar.com/docs/guides/scope/
+    #   This parameter is optional and should normally be set within the Smartcar Dashboard.
+    #   Can also be a Hash of options if scope is not needed.
     # @param [Hash] options
     # @option options[:force_prompt] [Boolean] - Setting `force_prompt` to
     # `true` will show the permissions approval screen on every authentication
@@ -53,9 +57,19 @@ module Smartcar
     # For a complete list of supported makes, please see our
     # [API Reference](https://smartcar.com/docs/api#authorization) documentation.
     # @option options[:flags] [Hash] - A hash of flag name string as key and a string or boolean value.
+    # @option options[:user] [String] - An optional unique identifier for a vehicle owner. This identifier
+    # is used to aggregate analytics across Connect sessions for each vehicle owner.
     #
     # @return [String] Authorization URL string
-    def get_auth_url(scope, options = {})
+    def get_auth_url(scope_or_options = {}, options = {})
+      scope = nil
+      if scope_or_options.is_a?(Array)
+        scope = scope_or_options
+        options ||= {}
+      elsif scope_or_options.is_a?(Hash)
+        options = scope_or_options
+      end
+
       initialize_auth_parameters(scope, options)
       add_single_select_options(options[:single_select])
       connect_client.auth_code.authorize_url(@auth_parameters)
@@ -124,14 +138,15 @@ module Smartcar
     def initialize_auth_parameters(scope, options)
       @auth_parameters = {
         response_type: CODE,
-        redirect_uri: redirect_uri,
-        mode: mode,
-        scope: scope.join(' ')
+        mode: mode
       }
+      @auth_parameters[:redirect_uri] = redirect_uri if redirect_uri
+      @auth_parameters[:scope] = scope.join(' ') if scope
       @auth_parameters[:approval_prompt] = options[:force_prompt] ? FORCE : AUTO unless options[:force_prompt].nil?
       @auth_parameters[:state] = options[:state] if options[:state]
       @auth_parameters[:make] = options[:make_bypass] if options[:make_bypass]
       @auth_parameters[:flags] = build_flags(options[:flags]) if options[:flags]
+      @auth_parameters[:user] = options[:user] if options[:user]
     end
 
     def add_single_select_options(single_select)

data/lib/smartcar/utils.rb

@@ -15,12 +15,19 @@ module Smartcar
 
     # gets a given env variable, checks for existence and throws exception if not present
     # @param config_name [String] key of the env variable
+    # @param options [Hash] options hash, supports :nullable key (default: false)
     #
     # @return [String] value of the env variable
-    def get_config(config_name)
+    def get_config(config_name, options = {})
       # ENV.MODE is set to test by e2e tests.
       config_name = "E2E_#{config_name}" if ENV['MODE'] == 'test'
-      raise Smartcar::ConfigNotFound, "Environment variable #{config_name} not found !" unless ENV[config_name]
+
+      unless ENV[config_name]
+        nullable = options.fetch(:nullable, false)
+        return nil if nullable
+
+        raise Smartcar::ConfigNotFound, "Environment variable #{config_name} not found !"
+      end
 
       ENV.fetch(config_name, nil)
     end
@@ -34,29 +41,101 @@ module Smartcar
     #
     # @return [RecursiveOpenStruct]
     def json_to_ostruct(hash)
-      RecursiveOpenStruct.new(hash, recurse_over_arrays: true)
+      convert_to_ostruct_recursively(hash)
+    end
+
+    # Helper method to recursively convert hashes and arrays to RecursiveOpenStruct
+    def convert_to_ostruct_recursively(obj)
+      case obj
+      when Array
+        obj.map { |el| convert_to_ostruct_recursively(el) }
+      when Hash
+        RecursiveOpenStruct.new(
+          obj.transform_values { |value| convert_to_ostruct_recursively(value) },
+          recurse_over_arrays: true
+        )
+
+      else
+        obj
+      end
+    end
+
+    # Helper method to convert string from camelCase or kebab-case to snake_case
+    def to_snake_case(str)
+      str.to_s
+         .gsub('-', '_') # Convert kebab-case to snake_case
+         .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+         .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+         .downcase
+    end
+
+    # Helper method to recursively convert hash keys to snake_case
+    def deep_transform_keys_to_snake_case(obj)
+      case obj
+      when Array
+        obj.map { |el| deep_transform_keys_to_snake_case(el) }
+      when Hash
+        obj.each_with_object({}) do |(key, value), result|
+          new_key = to_snake_case(key)
+          result[new_key] = deep_transform_keys_to_snake_case(value)
+        end
+      else
+        obj
+      end
+    end
+
+    # Parse date string to DateTime or return nil on error
+    def parse_date_safely(date_string)
+      return nil unless date_string
+
+      begin
+        DateTime.parse(date_string)
+      rescue ArgumentError
+        nil
+      end
     end
 
     def build_meta(headers)
       meta_hash = {
         'sc-data-age' => :data_age,
         'sc-unit-system' => :unit_system,
-        'sc-request-id' => :request_id
+        'sc-request-id' => :request_id,
+        'sc-fetched-at' => :fetched_at
       }.each_with_object({}) do |(header_name, key), meta|
         meta[key] = headers[header_name] if headers[header_name]
       end
-      meta = json_to_ostruct(meta_hash)
-      meta.data_age &&= DateTime.parse(meta.data_age)
 
+      meta = json_to_ostruct(meta_hash)
+      meta.data_age = parse_date_safely(meta.data_age)
+      meta.fetched_at = parse_date_safely(meta.fetched_at)
       meta
     end
 
     def build_response(body, headers)
-      response = json_to_ostruct(body)
-      response.meta = build_meta(headers)
+      # Check if body is already parsed (i.e., a Hash) or if it needs parsing (i.e., a String)
+      body_data = body.is_a?(String) ? JSON.parse(body) : body
+      if body_data.is_a?(Array)
+        response = OpenStruct.new(items: json_to_ostruct(body), meta: build_meta(headers))
+      else
+        response = json_to_ostruct(body)
+        response.meta = build_meta(headers)
+      end
       response
     end
 
+    def build_v3_response(body, headers)
+      body_data = body.is_a?(String) ? JSON.parse(body) : body
+      headers_data = headers.is_a?(String) ? JSON.parse(headers) : headers
+
+      body_snake = deep_transform_keys_to_snake_case(body_data)
+      headers_snake = deep_transform_keys_to_snake_case(headers_data)
+
+      OpenStruct.new(
+        body: json_to_ostruct(body_snake),
+        headers: json_to_ostruct(headers_snake)
+      )
+    end
+
     def build_aliases(response, aliases)
       (aliases || []).each do |original_name, alias_name|
         # rubocop:disable Lint/SymbolConversion
@@ -129,6 +208,9 @@ module Smartcar
 
       return :lock_status if path == '/security'
 
+      return :diagnostic_system_status if path == '/diagnostics/system_status'
+      return :diagnostic_trouble_codes if path == '/diagnostics/dtcs'
+
       path.split('/').reject(&:empty?).join('_').to_sym
     end
 

data/lib/smartcar/vehicle.rb

@@ -25,10 +25,17 @@ module Smartcar
         aliases: { 'percentRemaining' => 'percentage_remaining' }
       },
       battery_capacity: { path: proc { |id| "/vehicles/#{id}/battery/capacity" } },
+      nominal_capacity: { path: proc { |id| "/vehicles/#{id}/battery/nominal_capacity" } },
       charge: {
         path: proc { |id| "/vehicles/#{id}/charge" },
         aliases: { 'isPluggedIn' => 'is_plugged_in?' }
       },
+      diagnostic_system_status: {
+        path: proc { |id| "/vehicles/#{id}/diagnostics/system_status" }
+      },
+      diagnostic_trouble_codes: {
+        path: proc { |id| "/vehicles/#{id}/diagnostics/dtcs" }
+      },
       engine_oil: {
         path: proc { |id| "/vehicles/#{id}/engine/oil" },
         aliases: { 'lifeRemaining' => 'life_remaining' }
@@ -42,6 +49,16 @@ module Smartcar
       },
       location: { path: proc { |id| "/vehicles/#{id}/location" } },
       odometer: { path: proc { |id| "/vehicles/#{id}/odometer" } },
+      service_history: {
+        path: proc { |id, start_date = nil, end_date = nil|
+          base_path = "/vehicles/#{id}/service/history"
+          query_params = []
+          query_params << "start_date=#{start_date}" unless start_date.nil?
+          query_params << "end_date=#{end_date}" unless end_date.nil?
+          "#{base_path}?#{query_params.join('&')}" unless query_params.empty?
+        },
+        skip: true
+      },
       tire_pressure: {
         path: proc { |id| "/vehicles/#{id}/tires/pressure" },
         aliases: {
@@ -129,6 +146,14 @@ module Smartcar
     # @return [OpenStruct] And object representing the JSON response mentioned in https://smartcar.com/docs/api#get-ev-battery-capacity
     #  and a meta attribute with the relevant items from response headers.
 
+    # @!method nominal_capacity()
+    # Returns a list of nominal rated battery capacities for a vehicle.
+    #
+    # API Documentation https://smartcar.com/docs/api-reference/get-nominal-capacity
+    #
+    # @return [OpenStruct] And object representing the JSON response mentioned in https://smartcar.com/docs/api-reference/get-nominal-capacity
+    #  and a meta attribute with the relevant items from response headers.
+
     # @!method charge()
     # Returns the current charge status of the vehicle.
     #
@@ -137,6 +162,20 @@ module Smartcar
     # @return [OpenStruct] And object representing the JSON response mentioned in https://smartcar.com/docs/api#get-ev-battery
     #  and a meta attribute with the relevant items from response headers.
 
+    # @!method diagnostic_system_status()
+    # Returns the status of the vehicle's diagnostic systems.
+    #
+    # API Documentation: https://smartcar.com/docs/api#get-diagnostic-system-status
+    #
+    # @return [OpenStruct] An object representing the diagnostic system status and metadata.
+
+    # @!method diagnostic_trouble_codes()
+    # Retrieves diagnostic trouble codes (DTCs) from the vehicle.
+    #
+    # API Documentation: https://smartcar.com/docs/api#get-diagnostic-trouble-codes
+    #
+    # @return [OpenStruct] An object containing the DTCs and metadata.
+
     # @!method engine_oil()
     # Returns the remaining life span of a vehicle's engine oil
     #
@@ -232,6 +271,40 @@ module Smartcar
       build_response(response, headers)
     end
 
+    # Retrieves a list of service records for the vehicle, optionally filtered by a specified date range.
+    # If no dates are specified, the method defaults to returning records from the last year.
+    #
+    # This method calls the Smartcar API to fetch the vehicle's service history and processes the
+    # response to return structured data.
+    #
+    # @param start_date [String, nil] the start date of the period from which records are retrieved (inclusive).
+    #                                 Expected in 'YYYY-MM-DD' format. If nil, defaults to one year ago from today.
+    # @param end_date [String, nil] the end date of the period until which records are retrieved (inclusive).
+    #                               Expected in 'YYYY-MM-DD' format. If nil, defaults to today's date.
+    #
+    # @return [OpenStruct] An object representing the parsed JSON response from the API, with service history
+    #         data and metadata extracted from the response headers.
+    #
+    # Example usage:
+    #   vehicle.service_history('2021-01-01', '2021-12-31')
+    #
+    # Note: This method assumes that the necessary error handling is embedded within the `get` method or handled
+    #       externally when exceptions arise due to network issues, API limitations, or data encoding problems.
+    def service_history(start_date = nil, end_date = nil)
+      start_date, end_date = default_date_range if start_date.nil? || end_date.nil?
+
+      path = METHODS[:service_history][:path].call(id, start_date, end_date)
+      body, headers = get(path, @query_params)
+      build_response(body, headers)
+    end
+
+    # Utility method to provide default dates
+    def default_date_range
+      end_date = DateTime.now.new_offset(0).to_date
+      start_date = end_date - 365
+      [start_date.to_s, end_date.to_s]
+    end
+
     # Subscribe the vehicle to given webhook Id.
     #
     # @param webhook_id [String] Webhook id to subscribe to
@@ -298,6 +371,34 @@ module Smartcar
       process_batch_response(response, headers)
     end
 
+    # Retrieve a specific signal by signal code from the vehicle.
+    # Uses the Vehicle API (v3) endpoint.
+    #
+    # API Documentation - https://smartcar.com/docs/api-reference/get-signal
+    #
+    # @param signal_code [String] The code of the signal to retrieve.
+    #
+    # @return [OpenStruct] An object with a "body" attribute containing the signal data
+    #   and a "headers" attribute containing the response headers.
+    def get_signal(signal_code)
+      raise InvalidParameterValue.new, 'signal_code is a required field' if signal_code.nil? || signal_code.empty?
+
+      path = "/vehicles/#{id}/signals/#{signal_code}"
+      request_v3(path)
+    end
+
+    # Retrieve all available signals from the vehicle.
+    # Uses the Vehicle API (v3) endpoint.
+    #
+    # API Documentation - https://smartcar.com/docs/api-reference/get-signals
+    #
+    # @return [OpenStruct] An object with a "body" attribute containing all signals data
+    #   and a "headers" attribute containing the response headers.
+    def get_signals
+      path = "/vehicles/#{id}/signals"
+      request_v3(path)
+    end
+
     # General purpose method to make requests to the Smartcar API - can be
     # used to make requests to brand specific endpoints.
     #
@@ -314,5 +415,35 @@ module Smartcar
       meta = build_meta(headers)
       json_to_ostruct({ body: raw_response, meta: meta })
     end
+
+    private
+
+    # Makes a request to the v3 vehicles API using the vehicle API origin
+    #
+    # @param path [String] The API path to request.
+    #
+    # @return [OpenStruct] An object with body and headers attributes.
+    def request_v3(path)
+      vehicle_service = Faraday.new(
+        url: ENV['SMARTCAR_VEHICLE_API_ORIGIN'] || VEHICLE_API_ORIGIN,
+        request: { timeout: DEFAULT_REQUEST_TIMEOUT }
+      )
+
+      response = vehicle_service.get do |request|
+        request.headers['Authorization'] = "Bearer #{token}"
+        request.headers['Content-Type'] = 'application/json'
+        request.headers['User-Agent'] =
+          "Smartcar/#{VERSION} (#{RbConfig::CONFIG['host_os']}; #{RbConfig::CONFIG['arch']}) Ruby v#{RUBY_VERSION}"
+
+        complete_path = "/v3#{path}"
+        complete_path += "?#{URI.encode_www_form(@query_params.compact)}" unless @query_params.empty?
+        request.url complete_path
+      end
+
+      handle_error(response)
+
+      body = response.body.empty? ? '{}' : response.body
+      build_v3_response(body, response.headers.to_h)
+    end
   end
 end

data/lib/smartcar/version.rb

@@ -2,5 +2,5 @@
 
 module Smartcar
   # Gem current version number
-  VERSION = '3.8.0'
+  VERSION = '3.9.5'
 end

data/lib/smartcar.rb

@@ -15,6 +15,7 @@ module Smartcar
 
   # Host to connect to smartcar
   API_ORIGIN = 'https://api.smartcar.com/'
+  VEHICLE_API_ORIGIN = 'https://vehicle.api.smartcar.com'
   MANAGEMENT_API_ORIGIN = 'https://management.smartcar.com'
   PATHS = {
     compatibility: '/compatibility',
@@ -101,6 +102,49 @@ module Smartcar
       ))
     end
 
+    # Module method to retrieve the Smartcar compatibility matrix for a given region.
+    # Provides the ability to filter by scope, make, and type.
+    #
+    # A compatible vehicle is a vehicle that:
+    # 1. has the hardware required for internet connectivity,
+    # 2. belongs to the makes and models Smartcar supports, and
+    # 3. supports the permissions.
+    #
+    # API Documentation - https://smartcar.com/docs/api-reference/compatibility/by-region-and-make
+    # @param region [String] One of the following regions: US, CA, or EUROPE
+    # @param options [Hash] Optional parameters
+    # @option options [Array<String>] :scope List of permissions to filter the matrix by
+    # @option options [String, Array<String>] :make List of makes to filter the matrix by
+    #   (space-separated string or array)
+    # @option options [String] :type Engine type to filter the matrix by (e.g., "ICE", "HEV", "PHEV", "BEV")
+    # @option options [String] :client_id Client ID that overrides ENV
+    # @option options [String] :client_secret Client Secret that overrides ENV
+    # @option options [String] :version API version to use, defaults to what is globally set
+    # @option options [String] :mode Determine what mode Smartcar Connect should be launched in.
+    #   Should be one of test, live or simulated.
+    # @option options [Faraday::Connection] :service Optional connection object to be used for requests
+    #
+    # @return [OpenStruct] An object representing the compatibility matrix organized by make,
+    #  with each make containing an array of compatible models and a meta attribute with response headers.
+    def get_compatibility_matrix(region, options = {})
+      raise Base::InvalidParameterValue.new, 'region is a required field' if region.nil? || region.empty?
+
+      base_object = Base.new(
+        {
+          version: options[:version] || Smartcar.get_api_version,
+          auth_type: Base::BASIC,
+          service: options[:service]
+        }
+      )
+
+      base_object.token = generate_basic_auth(options, base_object)
+
+      base_object.build_response(*base_object.get(
+        "#{PATHS[:compatibility]}/matrix",
+        build_compatibility_matrix_params(region, options)
+      ))
+    end
+
     # Module method Used to get user id
     #
     # API Documentation - https://smartcar.com/docs/api#get-user
@@ -224,6 +268,45 @@ module Smartcar
       ))
     end
 
+    # Module method to retrieve vehicle information using the v3 API.
+    #
+    # API Documentation - https://smartcar.com/docs/api-reference/get-vehicle
+    # @param vehicle_id [String] The vehicle ID
+    # @param token [String] Access token
+    # @param options [Hash] Optional parameters
+    # @option options [Hash] :flags A hash of flag name string as key and a string or boolean value.
+    # @option options [Faraday::Connection] :service Optional connection object to be used for requests
+    #
+    # @return [OpenStruct] An object with a "body" attribute containing the vehicle data
+    #   and a "headers" attribute containing the response headers.
+    def get_vehicle(vehicle_id:, token:, options: {})
+      raise Base::InvalidParameterValue.new, 'vehicle_id is a required field' if vehicle_id.nil? || vehicle_id.empty?
+      raise Base::InvalidParameterValue.new, 'token is a required field' if token.nil? || token.empty?
+
+      vehicle_service = Faraday.new(
+        url: ENV['SMARTCAR_VEHICLE_API_ORIGIN'] || VEHICLE_API_ORIGIN,
+        request: { timeout: DEFAULT_REQUEST_TIMEOUT }
+      )
+
+      query_params = { flags: stringify_params(options[:flags]) }
+
+      response = vehicle_service.get do |request|
+        request.headers['Authorization'] = "Bearer #{token}"
+        request.headers['Content-Type'] = 'application/json'
+        request.headers['User-Agent'] =
+          "Smartcar/#{VERSION} (#{RbConfig::CONFIG['host_os']}; #{RbConfig::CONFIG['arch']}) Ruby v#{RUBY_VERSION}"
+
+        complete_path = "/v3/vehicles/#{vehicle_id}"
+        complete_path += "?#{URI.encode_www_form(query_params.compact)}" unless query_params.empty?
+        request.url complete_path
+      end
+
+      raise build_error(response.status, response.body, response.headers) unless [200, 204].include?(response.status)
+
+      body = response.body.empty? ? '{}' : response.body
+      build_v3_response(body, response.headers.to_h)
+    end
+
     # returns auth token for Basic vehicle management auth
     #
     # @return [String] Base64 encoding of default:amt
@@ -252,6 +335,29 @@ module Smartcar
       query_params
     end
 
+    def build_compatibility_matrix_params(region, options)
+      query_params = { region: region }
+
+      # Handle scope - convert array to space-separated string
+      if options[:scope]
+        query_params[:scope] = options[:scope].is_a?(Array) ? options[:scope].join(' ') : options[:scope]
+      end
+
+      # Handle make - convert array to space-separated string
+      if options[:make]
+        query_params[:make] = options[:make].is_a?(Array) ? options[:make].join(' ') : options[:make]
+      end
+
+      # Handle type
+      query_params[:type] = options[:type] if options[:type]
+
+      # Handle mode
+      mode = determine_mode(options[:test_mode], options[:mode])
+      query_params[:mode] = mode unless mode.nil?
+
+      query_params
+    end
+
     # returns auth token for Basic auth
     #
     # @return [String] Base64 encoding of CLIENT:SECRET

data/lib/smartcar_error.rb

@@ -2,7 +2,7 @@
 
 # Custom SmartcarError class to represent errors from Smartcar APIs.
 class SmartcarError < StandardError
-  attr_reader :code, :status_code, :request_id, :type, :description, :doc_url, :resolution, :detail, :retry_after
+  attr_reader :code, :status_code, :request_id, :type, :description, :doc_url, :resolution, :detail, :retry_after, :suggested_user_message
 
   def initialize(status, body, headers)
     @status_code = status

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: smartcar
 version: !ruby/object:Gem::Version
-  version: 3.8.0
+  version: 3.9.5
 platform: ruby
 authors:
 - Ashwin Subramanian
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-12-19 00:00:00.000000000 Z
+date: 2026-01-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -178,10 +178,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".buddy/cd.yml"
+- ".buddy/ci.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
-- ".travis.yml"
 - ".yardopts"
 - CODE_OF_CONDUCT.md
 - Gemfile

data/.travis.yml

@@ -1,28 +0,0 @@
-sudo: false
-language: ruby
-cache: bundler
-services:
-- xvfb
-addons:
-  firefox: latest
-rvm:
-- 2.7
-- 3.0
-before_install:
-  - gem install bundler -v 2.3.1
-  - wget https://github.com/mozilla/geckodriver/releases/download/v0.26.0/geckodriver-v0.26.0-linux64.tar.gz
-  - mkdir geckodriver
-  - tar -xzf geckodriver-v0.26.0-linux64.tar.gz -C geckodriver
-  - export PATH=$PATH:$PWD/geckodriver
-# install:
-# - firefox -headless &
-deploy:
-  provider: rubygems
-  api_key: $RUBYGEMSAPI_KEY
-  gem: smartcar
-  gemspec: ruby-sdk.gemspec
-  on:
-    tags: true
-    branch: master
-    rvm: 2.7
-  skip_cleanup: 'true'