apiverve_vindecoder 1.2.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a1ef0e2457f86148b2722fe0ba82a8b440327e6e98afc06c69823001a3a59885
+  data.tar.gz: a2c3e356d6e6e6048c7d4e73ac416b7ef9bb9216a4998507ee0d18baee5a8053
+SHA512:
+  metadata.gz: 53107a732499739611cf92c0545dc50ba859c997fde7b6c490a7906ec806bea827fcfe247c80941d2ac4c6d33f0ee3851899b18828a5da32f36acaf15cf0373a
+  data.tar.gz: a807bdfe206fd4e235ad572a77ce636ac64b65d759f8c9ed1a226475c4f130fd57c8f51c638adff35c11494060d83bb585f9b7278d95a066eb94787efa1c52d0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 APIVerve and EvlarSoft LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,284 @@
+# VIN Decoder API - Ruby Gem
+
+VIN Decoder turns a 17-character Vehicle Identification Number into the vehicle it identifies. Returns make, model, year, trim, body class and manufacturer, plus engine specifications, plant of manufacture, and the safety equipment fitted to that specific build. Optionally adds every safety recall issued for that vehicle and its NHTSA 5-star crash-test rating.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'apiverve_vindecoder'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install apiverve_vindecoder
+```
+
+## Getting Started
+
+Get your API key at [APIVerve](https://apiverve.com)
+
+### Basic Usage
+
+```ruby
+require 'apiverve_vindecoder'
+
+# Initialize the client
+client = APIVerve::Vindecoder::Client.new(api_key: "YOUR_API_KEY")
+
+# Make a request
+response = client.execute({
+  vin: "1HGCM82633A004352",
+  recalls: true,
+  safetyRating: true
+})
+
+# Print the response
+puts response
+```
+
+
+### Error Handling
+
+```ruby
+begin
+  response = client.execute({ vin: "1HGCM82633A004352", recalls: true, safetyRating: true })
+  puts response["data"]
+rescue APIVerve::Vindecoder::ValidationError => e
+  puts "Validation error: #{e.errors.join(', ')}"
+rescue APIVerve::Vindecoder::APIError => e
+  puts "API error: #{e.message}"
+  puts "Status code: #{e.status_code}"
+end
+```
+
+### Debug Mode
+
+```ruby
+# Enable debug logging
+client = APIVerve::Vindecoder::Client.new(
+  api_key: "YOUR_API_KEY",
+  debug: true
+)
+```
+
+## Example Response
+
+```json
+{
+  "status": "ok",
+  "error": null,
+  "data": {
+    "vin": "1HGCM82633A004352",
+    "valid": true,
+    "decoded": true,
+    "vehicleDescriptor": "1HGCM826*3A",
+    "make": "HONDA",
+    "model": "Accord",
+    "year": 2003,
+    "trim": "EX-V6",
+    "trim2": null,
+    "series": null,
+    "series2": null,
+    "manufacturer": "AMERICAN HONDA MOTOR CO., INC.",
+    "vehicleType": "PASSENGER CAR",
+    "bodyClass": "Coupe",
+    "plant": {
+      "state": "OHIO",
+      "country": "UNITED STATES (USA)",
+      "city": "MARYSVILLE"
+    },
+    "engine": {
+      "displacementL": "2.998832712",
+      "displacementCc": "2998.832712",
+      "engineNumberOfCylinders": "6",
+      "engineModel": "J30A4",
+      "engineConfiguration": "V-Shaped",
+      "engineBrakeHpFrom": "240",
+      "displacementCi": "183",
+      "fuelTypePrimary": "Gasoline",
+      "valveTrainDesign": "Single Overhead Cam (SOHC)"
+    },
+    "features": {
+      "passiveSafetySystem": {
+        "otherRestraintSystemInfo": "Seat Belt (Rr center position)",
+        "seatBeltType": "Manual",
+        "sideAirBagLocations": "1st Row (Driver and Passenger)",
+        "curtainAirBagLocations": "1st and 2nd Rows",
+        "frontAirBagLocations": "1st Row (Driver and Passenger)"
+      },
+      "exterior": {
+        "grossVehicleWeightRatingFrom": "Class 1C: 4,001 - 5,000 lb (1,814 - 2,268 kg)",
+        "grossVehicleWeightRatingTo": "Class 1: 6,000 lb or less (2,722 kg or less)",
+        "doors": "2"
+      },
+      "mechanical": {
+        "transmissionStyle": "Automatic",
+        "transmissionSpeeds": "5"
+      }
+    },
+    "validation": {
+      "errorText": "0 - VIN decoded clean. Check Digit (9th position) is correct",
+      "errorCode": "0",
+      "errorCodes": [
+        "0"
+      ]
+    },
+    "recalls": {
+      "count": 13,
+      "doNotDrive": false,
+      "parkOutside": false,
+      "bySeverity": {
+        "critical": 0,
+        "high": 10,
+        "medium": 3,
+        "low": 0
+      },
+      "latestReportedOn": "2019-06-27",
+      "items": [
+        {
+          "id": "19V499000",
+          "manufacturerRecallId": "Q5A, Y58",
+          "manufacturer": "Honda (American Honda Motor Co.)",
+          "reportedOn": "2019-06-27",
+          "ownersNotifiedOn": "2019-08-12",
+          "initiatedBy": "nhtsa",
+          "components": [
+            {
+              "system": "Air Bags",
+              "detail": "Frontal › Driver Side › Inflator Module"
+            }
+          ],
+          "summary": "Honda (American Honda Motor Co.) is recalling certain 2003 Acura 3.2CL, 2002-2003 3.2TL, 2003-2006 MDX, 2001-2007 Honda Accord, 2001-2005 Civic, 2003-2005 Civic Hybrid, 2001-2005 Civic GX NGV, 2002-2006 CR-V, 2003-2011 Element, 2002-2004 Odyssey, 2003-2008 Pilot and 2006 Ridgeline vehicles. These vehicles are equipped with driver frontal air bag inflators assembled as a recall remedy part or replacement service part, that may explode due to propellant degradation occurring after long-term exposure to high absolute humidity, temperature and temperature cycling.",
+          "consequence": "An inflator explosion may result in sharp metal fragments striking the driver or other occupants resulting in serious injury or death.",
+          "hazards": [
+            "injury",
+            "death"
+          ],
+          "doNotDrive": false,
+          "parkOutside": false,
+          "remedy": {
+            "description": "Honda will notify owners, and dealers will replace the driver frontal air bag inflator, free of charge. The recall began August 12, 2019. Owners may contact Honda customer service at 1-888-234-2138. Honda's numbers for this recall are Q5A and Y58.",
+            "status": "available",
+            "overTheAir": false,
+            "freeOfCharge": true
+          },
+          "unitsAffected": 3947,
+          "manufactured": {
+            "from": "2000-07-10",
+            "to": "2011-02-22"
+          },
+          "scope": {
+            "makes": 2,
+            "models": 12,
+            "modelYears": {
+              "from": 2001,
+              "to": 2011
+            }
+          },
+          "url": "https://www.nhtsa.gov/recalls?nhtsaId=19V499000",
+          "severity": "high",
+          "match": "exact",
+          "listedAs": "ACCORD"
+        },
+        {
+          "id": "19V501000",
+          "manufacturerRecallId": "E5D, X5C",
+          "manufacturer": "Honda (American Honda Motor Co.)",
+          "reportedOn": "2019-06-27",
+          "ownersNotifiedOn": "2019-08-12",
+          "initiatedBy": "nhtsa",
+          "components": [
+            {
+              "system": "Air Bags",
+              "detail": "Frontal › Passenger Side › Inflator Module"
+            }
+          ],
+          "summary": "Honda (American Honda Motor Co.) is recalling certain 2003-2006 Acura MDX, 2005-2012 RL, 2003-2007 Honda Accord, 2001-2005 Civic, 2003-2005 Civic Hybrid, 2001-2005 Civic GX NGV, 2002-2006 CR-V, 2003-2011 Element, 2007-2008 Fit, 2002-2004 Odyssey, 2003-2008 Pilot, and 2006-2014 Ridgeline vehicles. The vehicles are equipped with passenger frontal air bag inflators assembled as a recall remedy part or replacement service part, that may explode due to propellant degradation occurring after long-term exposure to high absolute humidity, temperature and temperature cycling.",
+          "consequence": "An inflator explosion may result in sharp metal fragments striking the driver or other occupants resulting in serious injury or death.",
+          "hazards": [
+            "injury",
+            "death"
+          ],
+          "doNotDrive": false,
+          "parkOutside": false,
+          "remedy": {
+            "description": "Honda will notify owners, and dealers will replace the passenger frontal airbag inflator, free of charge. The recall began August 12, 2019. Owners may contact Honda customer service at 1-888-234-2138. Honda's numbers for this recall are E5D and X5C.",
+            "status": "available",
+            "overTheAir": false,
+            "freeOfCharge": true
+          },
+          "unitsAffected": 1657752,
+          "manufactured": {
+            "from": "2000-04-25",
+            "to": "2014-06-02"
+          },
+          "scope": {
+            "makes": 2,
+            "models": 12,
+            "modelYears": {
+              "from": 2001,
+              "to": 2014
+            }
+          },
+          "url": "https://www.nhtsa.gov/recalls?nhtsaId=19V501000",
+          "severity": "high",
+          "match": "exact",
+          "listedAs": "ACCORD"
+        }
+      ]
+    },
+    "safetyRating": {
+      "testedVehicle": "2003 Honda Accord 2-DR. w/SAB",
+      "match": "exact",
+      "variantsTested": 4,
+      "overall": null,
+      "frontal": {
+        "overall": null,
+        "driver": 5,
+        "passenger": 5
+      },
+      "side": {
+        "overall": null,
+        "driver": null,
+        "passenger": null,
+        "barrier": null,
+        "pole": null,
+        "frontSeat": null,
+        "rearSeat": null
+      },
+      "rollover": {
+        "rating": 4,
+        "riskPercent": null,
+        "tipped": null
+      },
+      "driverAssist": {
+        "electronicStabilityControl": "notAvailable",
+        "forwardCollisionWarning": "notAvailable",
+        "laneDepartureWarning": "notAvailable"
+      }
+    }
+  }
+}
+```
+
+## Documentation
+
+For more information, visit the [API Documentation](https://docs.apiverve.com/ref/vindecoder?utm_source=rubygems&utm_medium=referral&utm_content=readme).
+
+## Support
+
+- Website: [https://apiverve.com/marketplace/vindecoder?utm_source=ruby&utm_medium=referral&utm_content=readme](https://apiverve.com/marketplace/vindecoder?utm_source=ruby&utm_medium=referral&utm_content=readme)
+- Email: hello@apiverve.com
+
+## License
+
+This gem is available under the [MIT License](LICENSE).

data/lib/apiverve_vindecoder/client.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+require "json"
+
+module APIVerve
+  module Vindecoder
+    # Client for the VIN Decoder API
+    #
+    # @example Basic usage
+    #   client = APIVerve::Vindecoder::Client.new(api_key: "your_api_key")
+    #   response = client.execute({ vin: "1HGCM82633A004352", recalls: true, safetyRating: true })
+    #   puts response
+    #
+    # @see https://apiverve.com/marketplace/vindecoder?utm_source=ruby&utm_medium=referral&utm_content=readme
+    class Client
+      BASE_URL = "https://api.apiverve.com/v1/vindecoder"
+      DEFAULT_TIMEOUT = 30
+
+      # Validation rules for parameters
+      VALIDATION_RULES = { 'vin' => { type: 'string', required: true, min_length: 1, max_length: 17 }, 'recalls' => { type: 'boolean', required: false }, 'safetyRating' => { type: 'boolean', required: false } }
+
+      # Format validation patterns
+      FORMAT_PATTERNS = {
+        'email' => /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+        'url' => /^https?:\/\/.+/,
+        'ip' => /^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$|^([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}$/,
+        'date' => /^\d{4}-\d{2}-\d{2}$/,
+        'hexColor' => /^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/
+      }.freeze
+
+      # Initialize the client
+      #
+      # @param api_key [String] Your APIVerve API key
+      # @param timeout [Integer] Request timeout in seconds (default: 30)
+      # @param debug [Boolean] Enable debug logging (default: false)
+      # @raise [ArgumentError] If API key is invalid
+      def initialize(api_key:, timeout: DEFAULT_TIMEOUT, debug: false)
+        validate_api_key!(api_key)
+
+        @api_key = api_key
+        @timeout = timeout
+        @debug = debug
+
+        @connection = Faraday.new(url: BASE_URL) do |conn|
+          conn.request :multipart
+          conn.request :url_encoded
+          conn.adapter Faraday.default_adapter
+          conn.options.timeout = @timeout
+          conn.headers["x-api-key"] = @api_key
+          conn.headers["auth-mode"] = "rubygems-package"
+          conn.headers["Content-Type"] = "application/json"
+        end
+      end
+
+      # Execute the API request
+      #
+      # @param params [Hash] Query parameters or request body
+      # @return [Hash] API response
+      # @raise [APIError] If the request fails
+      # @raise [ValidationError] If parameter validation fails
+      def execute(params = {})
+        validate_params!(params)
+
+        log("Making GET request to #{BASE_URL}")
+        log("Parameters: #{params.inspect}") if params.any?
+
+        response = @connection.get do |req|
+          params.each { |k, v| req.params[k.to_s] = v }
+        end
+
+        handle_response(response)
+      end
+
+      private
+
+      def validate_api_key!(api_key)
+        raise ArgumentError, "API key is required. Get your API key at: https://apiverve.com" if api_key.nil? || api_key.strip.empty?
+
+        unless api_key.match?(/^[a-zA-Z0-9_-]+$/)
+          raise ArgumentError, "Invalid API key format. API key should only contain letters, numbers, hyphens, and underscores."
+        end
+      end
+
+      def validate_params!(params)
+        return if VALIDATION_RULES.empty?
+
+        errors = []
+
+        VALIDATION_RULES.each do |param_name, rules|
+          value = params[param_name.to_sym] || params[param_name]
+
+          # Check required
+          if rules[:required] && (value.nil? || value.to_s.empty?)
+            errors << "Required parameter [#{param_name}] is missing."
+            next
+          end
+
+          next if value.nil?
+
+          case rules[:type]
+          when "integer", "number"
+            begin
+              num_value = rules[:type] == "number" ? Float(value) : Integer(value)
+              errors << "Parameter [#{param_name}] must be at least #{rules[:min]}." if rules[:min] && num_value < rules[:min]
+              errors << "Parameter [#{param_name}] must be at most #{rules[:max]}." if rules[:max] && num_value > rules[:max]
+            rescue ArgumentError, TypeError
+              errors << "Parameter [#{param_name}] must be a valid #{rules[:type]}."
+            end
+          when "string"
+            unless value.is_a?(String)
+              errors << "Parameter [#{param_name}] must be a string."
+              next
+            end
+            errors << "Parameter [#{param_name}] must be at least #{rules[:min_length]} characters." if rules[:min_length] && value.length < rules[:min_length]
+            errors << "Parameter [#{param_name}] must be at most #{rules[:max_length]} characters." if rules[:max_length] && value.length > rules[:max_length]
+
+            if rules[:format] && FORMAT_PATTERNS[rules[:format]]
+              unless value.match?(FORMAT_PATTERNS[rules[:format]])
+                errors << "Parameter [#{param_name}] must be a valid #{rules[:format]}."
+              end
+            end
+          when "boolean"
+            unless [true, false, "true", "false"].include?(value)
+              errors << "Parameter [#{param_name}] must be a boolean."
+            end
+          end
+
+          # Enum validation
+          if rules[:enum] && !rules[:enum].include?(value)
+            errors << "Parameter [#{param_name}] must be one of: #{rules[:enum].join(', ')}."
+          end
+        end
+
+        raise ValidationError, errors unless errors.empty?
+      end
+
+      def handle_response(response)
+        log("Response status: #{response.status}")
+
+        data = JSON.parse(response.body)
+
+        if data["status"] == "error"
+          raise APIError.new(data["error"] || "Unknown API error", response.status, data)
+        end
+
+        unless response.success?
+          raise APIError.new(data["error"] || "HTTP #{response.status} error", response.status, data)
+        end
+
+        log("Request successful")
+        data
+      rescue JSON::ParserError => e
+        raise APIError.new("Invalid JSON response: #{e.message}", response.status)
+      end
+
+      def log(message)
+        puts "[APIVerve::Vindecoder] #{message}" if @debug
+      end
+    end
+
+    # Custom error class for API errors
+    class APIError < StandardError
+      attr_reader :status_code, :response
+
+      def initialize(message, status_code = nil, response = nil)
+        @status_code = status_code
+        @response = response
+        super(message)
+      end
+    end
+
+    # Custom error class for validation errors
+    class ValidationError < StandardError
+      attr_reader :errors
+
+      def initialize(errors)
+        @errors = errors
+        super("Validation failed: #{errors.join(' ')}")
+      end
+    end
+  end
+end

data/lib/apiverve_vindecoder.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "apiverve_vindecoder/client"
+
+module APIVerve
+  module Vindecoder
+    VERSION = "1.2.2"
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: apiverve_vindecoder
+version: !ruby/object:Gem::Version
+  version: 1.2.2
+platform: ruby
+authors:
+- APIVerve
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-10-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: VIN Decoder turns a 17-character Vehicle Identification Number into the
+  vehicle it identifies. Returns make, model, year, trim, body class and manufacturer,
+  plus engine specifications, plant of manufacture, and the safety equipment fitted
+  to that specific build. Optionally adds every safety recall issued for that vehicle
+  and its NHTSA 5-star crash-test rating.
+email:
+- hello@apiverve.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/apiverve_vindecoder.rb
+- lib/apiverve_vindecoder/client.rb
+homepage: https://apiverve.com/marketplace/vindecoder?utm_source=ruby&utm_medium=referral&utm_content=homepage
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://apiverve.com/marketplace/vindecoder?utm_source=ruby&utm_medium=referral&utm_content=homepage
+  source_code_uri: https://github.com/apiverve/vindecoder-API/tree/main/ruby
+  changelog_uri: https://apiverve.com/changelog
+  documentation_uri: https://docs.apiverve.com/ref/vindecoder
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: VIN Decoder API - Ruby Client
+test_files: []