vehicles 0.1.0

data/lib/generators/vehicles/install_generator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Vehicles
+  module Generators
+    # `rails generate vehicles:install`
+    #
+    # Writes a configuration initializer and an optional refresh job. There is
+    # deliberately NO migration: `vehicles` ships its dataset bundled in the gem
+    # and reads it from memory, so there's no table to create and nothing to seed.
+    # The gem works the moment it's in your Gemfile; this generator gives you a
+    # place to set a region / API key, and a job to keep the data current without
+    # waiting for a gem upgrade.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/vehicles.rb"
+      end
+
+      def create_refresh_job
+        template "vehicles_refresh_job.rb", "app/jobs/vehicles_refresh_job.rb"
+      end
+
+      def display_post_install_message
+        say "\n🚗 vehicles installed!", :green
+        say "\nNo migration needed — the dataset ships inside the gem and just works."
+        say "\nTry it now:"
+        say "  Vehicles.makes                 # => [\"Alfa Romeo\", \"Audi\", ...]", :cyan
+        say "  Vehicles.models(\"VW\")          # => [\"Golf\", \"Polo\", ...]", :cyan
+        say "  Vehicles.make_options          # => [[\"Audi\", \"audi\"], ...]  (for select)", :cyan
+        say "\nConfig (optional) lives in config/initializers/vehicles.rb."
+        say "Add a VehiclesDB API key there to unlock years, images, and segments."
+        say "\nStay current WITHOUT a gem upgrade: schedule VehiclesRefreshJob", :yellow
+        say "(e.g. daily in config/recurring.yml) to pull the latest published data.\n"
+      end
+    end
+  end
+end

data/lib/generators/vehicles/templates/initializer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# vehicles configuration.
+#
+# Everything here is OPTIONAL — the gem ships sensible defaults and a bundled
+# dataset, so it works with zero configuration. Uncomment what you need.
+
+Vehicles.configure do |config|
+  # Default region for queries. Today the bundled data covers the EU market;
+  # :us / :gb / :au / :nz / :ca packs are on the roadmap (the API is already
+  # region-aware, so adding them won't change your code).
+  # config.region = :eu
+
+  # Optional: a VehiclesDB API key unlocks hosted enrichment — production years,
+  # model images (year- and color-accurate), and market segments — on the same
+  # Vehicles::Model objects you already use. Without a key, everything still
+  # works on the bundled data; those richer fields just return nil.
+  # config.api_key = ENV["VEHICLESDB_API_KEY"]
+
+  # Optional: your own make aliases, merged over the built-ins. Matched
+  # forgivingly (case/diacritics-insensitive).
+  # config.aliases = { "Chevy" => "Chevrolet", "Landy" => "Land Rover" }
+
+  # --- Data refresh (optional) ----------------------------------------------
+  # The gem works offline with its bundled snapshot. To get data fixes and new
+  # makes WITHOUT upgrading the gem, schedule VehiclesRefreshJob (see app/jobs)
+  # — it pulls the latest published dataset into a local cache, which loads
+  # prefer over the bundled copy. Defaults below are sensible; override if needed.
+  #
+  # config.data_url   = "https://cdn.jsdelivr.net/gh/vehiclesdb/vehiclesdb@latest/dist/vehicles.json"
+  # config.cache_path = Rails.root.join("tmp", "cache", "vehicles", "vehicles.json")
+  # config.use_cache  = true   # set false to always use the bundled snapshot (fully offline/deterministic)
+end

data/lib/generators/vehicles/templates/vehicles_refresh_job.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Pulls the latest published VehiclesDB dataset into the local cache, so data
+# fixes and new makes reach this app WITHOUT a gem upgrade. Schedule it (daily is
+# plenty) — e.g. with solid_queue in config/recurring.yml:
+#
+#   vehicles_refresh:
+#     class: VehiclesRefreshJob
+#     schedule: every day at 3am
+#
+# It's safe to run anytime: it never raises, and a failed/partial download leaves
+# your current data untouched (the gem keeps serving the cache, or the bundled
+# snapshot if there's no cache yet).
+class VehiclesRefreshJob < ApplicationJob
+  queue_as :default
+
+  def perform
+    Vehicles.refresh!
+  end
+end

data/lib/vehicles/color.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Vehicles
+  # A canonical vehicle color. Reference data, not RDW-derived: a small, stable
+  # palette every consumer (and, in time, the hosted VehiclesDB image API) can
+  # share, so "red" means the same thing — and maps to the same image variant —
+  # everywhere. Display names are English; localize in your app (the slug is the
+  # stable, locale-independent key you store). `hex` is a representative swatch
+  # for UI chips / future color-accurate imagery.
+  class Color
+    attr_reader :slug, :name, :hex
+
+    def initialize(slug, name, hex)
+      @slug = slug
+      @name = name
+      @hex  = hex
+      freeze
+    end
+
+    def to_h
+      { slug: slug, name: name, hex: hex }
+    end
+
+    def to_s
+      name
+    end
+
+    def ==(other)
+      other.is_a?(Color) && other.slug == slug
+    end
+    alias eql? ==
+
+    def hash
+      slug.hash
+    end
+
+    def inspect
+      %(#<Vehicles::Color #{slug} "#{name}" #{hex}>)
+    end
+  end
+end

data/lib/vehicles/colors.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Vehicles
+  # The canonical color palette — the ~handful of colors that cover virtually
+  # every car on the road, plus an explicit `other` catch-all. Ordered roughly by
+  # real-world frequency (white/black/grey lead the global fleet) so a dropdown
+  # reads sensibly. Slugs are the stable keys you store; names are English labels
+  # to localize; hexes are representative swatches.
+  module Colors
+    ALL = [
+      Color.new("white",  "White",  "#F4F4F4"),
+      Color.new("black",  "Black",  "#1B1B1B"),
+      Color.new("grey",   "Grey",   "#8A8D90"),
+      Color.new("silver", "Silver", "#C7CCD1"),
+      Color.new("blue",   "Blue",   "#27408B"),
+      Color.new("red",    "Red",    "#B81D24"),
+      Color.new("green",  "Green",  "#2E6B3E"),
+      Color.new("brown",  "Brown",  "#5A3A22"),
+      Color.new("beige",  "Beige",  "#D9C6A5"),
+      Color.new("orange", "Orange", "#E8731A"),
+      Color.new("yellow", "Yellow", "#F2C200"),
+      Color.new("gold",   "Gold",   "#C8A951"),
+      Color.new("purple", "Purple", "#6B3FA0"),
+      Color.new("other",  "Other",  "#9AA0A6")
+    ].freeze
+
+    # Accept a few common spellings/synonyms so lookups are forgiving like the
+    # rest of the gem (normalized keys → canonical slug).
+    SYNONYMS = {
+      "gray" => "grey",
+      "silvery" => "silver",
+      "tan" => "beige",
+      "cream" => "beige",
+      "burgundy" => "red",
+      "navy" => "blue"
+    }.freeze
+
+    BY_SLUG = ALL.to_h { |c| [c.slug, c] }.freeze
+    BY_NAME = ALL.to_h { |c| [Vehicles.normalize(c.name), c] }.freeze
+  end
+end

data/lib/vehicles/configuration.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Vehicles
+  # The single source of truth for every knob. Sensible defaults mean you can use
+  # the whole gem without ever touching this — `Vehicles.configure` is opt-in.
+  #
+  #   Vehicles.configure do |config|
+  #     config.region  = :eu
+  #     config.api_key = ENV["VEHICLESDB_API_KEY"]
+  #     config.aliases = { "Chevy" => "Chevrolet" }
+  #   end
+  class Configuration
+    # Default region for queries. Today the bundled data ships :eu; the API is
+    # already region-aware so :us/:gb/etc. are additive, never breaking.
+    attr_accessor :region
+
+    # Optional VehiclesDB API key. When set, the hosted provider activates and
+    # enriches models with years/images/segments. When nil, everything still
+    # works on the bundled data — the gem is standalone first, SDK second.
+    attr_accessor :api_key
+
+    # Base URL for the hosted VehiclesDB API. Overridable for self-hosting/testing.
+    attr_accessor :api_base_url
+
+    # Network timeout (seconds) for hosted API calls. Kept short so a slow/missing
+    # API never blocks a request — hosted lookups degrade to the local data.
+    attr_accessor :api_timeout
+
+    # Extra make aliases, merged over the built-in ones. Keys are matched
+    # forgivingly (case/diacritics-insensitive); values are canonical make names.
+    attr_reader :aliases
+
+    # --- data refresh (optional) ---------------------------------------------
+    # The gem ships a bundled snapshot that works offline with zero setup. These
+    # let an app pull the latest published dataset (e.g. via a daily job) so data
+    # fixes and new makes land WITHOUT a gem upgrade.
+
+    # Where `Vehicles.refresh!` pulls the latest dataset. Defaults to the public
+    # VehiclesDB data repo via jsDelivr's CDN (always-latest release tag).
+    attr_accessor :data_url
+
+    # Where a refreshed dataset is cached on disk. Defaults to the app's cache dir
+    # (Rails) or the system temp dir. The refresh writes here; loads prefer it.
+    attr_accessor :cache_path
+
+    # Prefer a refreshed (cached) dataset over the bundled one when present.
+    # Set false to always use the bundled snapshot (fully offline/deterministic).
+    attr_accessor :use_cache
+
+    # Network timeout (seconds) for a refresh download.
+    attr_accessor :refresh_timeout
+
+    def initialize
+      @region          = :eu
+      @api_key         = nil
+      @api_base_url    = "https://api.vehiclesdb.com"
+      @api_timeout     = 2
+      @aliases         = {}
+      @data_url        = "https://cdn.jsdelivr.net/gh/vehiclesdb/vehiclesdb@latest/dist/vehicles.json"
+      @cache_path      = default_cache_path
+      @use_cache       = true
+      @refresh_timeout = 5
+    end
+
+    # Normalize alias keys at assignment time so lookups stay O(1) and forgiving.
+    def aliases=(hash)
+      @aliases = (hash || {}).each_with_object({}) do |(k, v), memo|
+        memo[Vehicles.normalize(k)] = v.to_s
+      end
+    end
+
+    private
+
+    # tmp/cache/vehicles under a Rails app, else a stable spot in the system temp
+    # dir. Refreshable data, so a cache-style location is appropriate.
+    def default_cache_path
+      base =
+        if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+          Rails.root.join("tmp", "cache", "vehicles")
+        else
+          require "tmpdir"
+          File.join(Dir.tmpdir, "vehicles")
+        end
+      File.join(base.to_s, "vehicles.json")
+    end
+  end
+end

data/lib/vehicles/dataset.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Vehicles
+  # Loads the bundled snapshot once, builds in-memory indexes, and answers every
+  # query. No HTTP, no SQLite, no ActiveRecord on the read path — the first call
+  # builds the index, every call after is a hash lookup.
+  #
+  # Instances are memoized per data path (see .load), so the JSON is parsed once
+  # per process.
+  class Dataset
+    # Built-in make aliases (normalized key => make slug). Common abbreviations
+    # and nicknames so whatever a user types tends to land. Diacritics and case
+    # are already handled by Vehicles.normalize, so "škoda"/"citroën" need no entry.
+    BUILTIN_ALIASES = {
+      "vw" => "volkswagen", "vdub" => "volkswagen",
+      "merc" => "mercedes-benz", "mercedes" => "mercedes-benz", "benz" => "mercedes-benz",
+      "mb" => "mercedes-benz",
+      "chevy" => "chevrolet",
+      "beemer" => "bmw", "bimmer" => "bmw",
+      "alfa" => "alfa-romeo",
+      "landrover" => "land-rover", "range rover" => "land-rover", "rangerover" => "land-rover",
+      "vauxhall" => "opel" # GB badge-engineered Opel; map to the EU make we ship
+    }.freeze
+
+    class << self
+      # Memoized per path so the bundled JSON is parsed only once per process.
+      def load(path = Vehicles.data_path)
+        (@instances ||= {})[path] ||= new(JSON.parse(File.read(path)))
+      end
+
+      # Drop the cache (used by the test suite between runs).
+      def reset!
+        @instances = {}
+      end
+    end
+
+    attr_reader :version, :schema_version, :region
+
+    def initialize(raw)
+      @version        = raw["version"]
+      @schema_version = raw["schema_version"]
+      @region         = raw["region"]
+
+      @makes    = (raw["makes"] || []).map { |attrs| Make.new(attrs) }
+      @by_slug  = {}   # raw slug => Make
+      @index    = {}   # normalized name/slug/alias => Make
+      @makes.each do |make|
+        @by_slug[make.slug] = make
+        index(make.name, make)
+        index(make.slug, make)
+        make.aliases.each { |a| index(a, make) }
+      end
+    end
+
+    # All makes, optionally filtered by kind/region. Unknown region => [] (honest:
+    # we don't ship that pack yet), so callers never get wrong-region data.
+    def makes(kind: nil, region: nil)
+      return [] if region && !region_match?(region)
+
+      list = @makes
+      list = list.select { |m| m.kinds.include?(kind.to_sym) } if kind
+      list
+    end
+
+    # Resolve a make from a String/Symbol/Make via aliases, slug, or name.
+    def find_make(query)
+      return query if query.is_a?(Make)
+
+      q = Vehicles.normalize(query)
+      return nil if q.empty?
+
+      # 1. user-supplied aliases win
+      if (canonical = Vehicles.configuration.aliases[q])
+        return @by_slug[Vehicles.slugify(canonical)] || @index[Vehicles.normalize(canonical)]
+      end
+      # 2. built-in aliases
+      if (slug = BUILTIN_ALIASES[q])
+        return @by_slug[slug]
+      end
+
+      # 3. direct slug / normalized name / make alias
+      @by_slug[q] || @index[q]
+    end
+
+    # Resolve a free-text "make + model" string into one Model. Tries the longest
+    # leading make prefix first ("land rover defender"), then the remainder as the
+    # model. Returns nil if nothing matches.
+    def find_model(query)
+      q = Vehicles.normalize(query)
+      tokens = q.split
+      return nil if tokens.empty?
+
+      (tokens.length - 1).downto(1) do |i|
+        make = find_make(tokens[0, i].join(" "))
+        next unless make
+
+        model = make.model(tokens[i..].join(" "))
+        return model if model
+      end
+      nil
+    end
+
+    # Every model whose name (or full name) matches the query, ranked: exact name,
+    # then prefix, then substring, then full-name substring. Shorter names first.
+    def search(query)
+      q = Vehicles.normalize(query)
+      return [] if q.empty?
+
+      scored = []
+      all_models.each do |m|
+        name_n = Vehicles.normalize(m.name)
+        score =
+          if    name_n == q              then 0
+          elsif name_n.start_with?(q)    then 1
+          elsif name_n.include?(q)       then 2
+          elsif Vehicles.normalize(m.full_name).include?(q) then 3
+          else next
+          end
+        scored << [score, m.name.length, m]
+      end
+      scored.sort_by { |score, len, _m| [score, len] }.map { |_s, _l, m| m }
+    end
+
+    # Flat list of every Model (memoized + frozen — shared, so don't let callers
+    # mutate it). Backs `search`.
+    def all_models
+      @all_models ||= @makes.flat_map(&:models).freeze
+    end
+
+    # Does this snapshot cover the given region? (Today only :eu.)
+    def region?(region)
+      region_match?(region)
+    end
+
+    private
+
+    def index(key, make)
+      @index[Vehicles.normalize(key)] ||= make
+    end
+
+    def region_match?(region)
+      Vehicles.normalize(region) == Vehicles.normalize(@region)
+    end
+  end
+end

data/lib/vehicles/make.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Vehicles
+  # A vehicle make, e.g. "Volkswagen", and the models it builds. Immutable value
+  # object. Its models are built lazily once and cached.
+  #
+  #   make = Vehicles.make("Audi")
+  #   make.slug       # => "audi"
+  #   make.models     # => ["A3", "A4", "Q3", ...]
+  #   make.model("a3")# => #<Vehicles::Model "Audi A3">
+  class Make
+    attr_reader :name, :slug, :aliases, :kinds
+
+    def initialize(attrs)
+      @name    = attrs["name"]
+      @slug    = attrs["slug"]
+      @aliases = Array(attrs["aliases"]).freeze
+      @kinds   = Array(attrs["kinds"]).map(&:to_sym).freeze
+      @raw_models = attrs["models"] || []
+    end
+
+    # All models for this make, optionally filtered by kind/body_type.
+    # Returns Vehicles::Model objects, ordered by popularity (as built).
+    # The unfiltered list is memoized AND frozen — it's shared process-wide, so a
+    # frozen array turns accidental caller mutation into a loud error instead of
+    # silently corrupting the dataset. Filtered calls return a fresh array.
+    def models(kind: nil, body_type: nil)
+      list = (@models ||= @raw_models.map { |m| Model.new(m, make: name, make_slug: slug) }.freeze)
+      list = list.select { |m| m.kind == kind.to_sym }           if kind
+      list = list.select { |m| m.body_type == body_type.to_sym } if body_type
+      list
+    end
+
+    # Model display names — what you drop into a dropdown. => ["A3", "A4", ...]
+    def model_names(**filters)
+      models(**filters).map(&:name)
+    end
+
+    # [[label, value], ...] for Rails `select`. => [["A3", "a3"], ["A4", "a4"]]
+    def model_options(**filters)
+      models(**filters).map { |m| [m.name, m.model_slug] }
+    end
+
+    # Find one model within this make by exact (normalized) name or slug.
+    # "a3" / "A3" / "Q 3" resolve; partial input does NOT (so `model("a")`
+    # returns nil, not "A3" — important, since the vehicle_model validator relies
+    # on this). Fuzzy/partial matching lives in `Vehicles.search`.
+    def model(query)
+      q = Vehicles.normalize(query)
+      return nil if q.empty?
+
+      models.find { |m| Vehicles.normalize(m.name) == q || m.model_slug == q }
+    end
+
+    def to_h
+      { name: name, slug: slug, kinds: kinds, models: model_names }
+    end
+
+    def to_s
+      name
+    end
+
+    def ==(other)
+      other.is_a?(Make) && other.slug == slug
+    end
+    alias eql? ==
+
+    def hash
+      slug.hash
+    end
+
+    def inspect
+      %(#<Vehicles::Make "#{name}">)
+    end
+  end
+end

data/lib/vehicles/model.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Vehicles
+  # A single vehicle nameplate, e.g. "Volkswagen Golf". A lightweight, immutable
+  # value object — no ActiveRecord, no mutation. Reads like English on purpose.
+  #
+  #   car = Vehicles.find("vw golf")
+  #   car.make        # => "Volkswagen"
+  #   car.name        # => "Golf"
+  #   car.full_name   # => "Volkswagen Golf"
+  #   car.body_type   # => :hatchback
+  #   car.suv?        # => false
+  class Model
+    # Vehicle kinds (RDW `voertuigsoort`). Today the bundled data is all :car;
+    # the shape already supports the rest for when those packs land.
+    KINDS = %i[car motorcycle van truck pickup trailer bus moped quad trike].freeze
+
+    # Body types — the sub-classification within a kind. For cars these are the
+    # familiar shapes; motorcycle styles (:naked, :adventure, …) reuse this field.
+    BODY_TYPES = %i[
+      hatchback sedan wagon suv mpv coupe convertible roadster pickup van
+    ].freeze
+
+    attr_reader :make, :make_slug, :name, :kind, :body_type
+
+    # @param attrs [Hash] one model entry from the dataset (name/slug/kind/body_type)
+    # @param make [String] the parent make's display name
+    # @param make_slug [String] the parent make's slug (for the composite slug)
+    def initialize(attrs, make:, make_slug:)
+      @make       = make
+      @make_slug  = make_slug
+      @name       = attrs["name"]
+      @model_slug = attrs["slug"]
+      @kind       = (attrs["kind"]      || "car").to_sym
+      @body_type  = (attrs["body_type"] || "hatchback").to_sym
+      freeze
+    end
+
+    # "Volkswagen Golf" — the natural label for a model on its own.
+    def full_name
+      "#{make} #{name}"
+    end
+    alias to_s full_name
+
+    # Composite, stable slug: "volkswagen-golf".
+    def slug
+      "#{make_slug}-#{@model_slug}"
+    end
+
+    # The bare model slug ("golf"), used as the value in `model_options`.
+    attr_reader :model_slug
+
+    # Predicate sugar: `car.suv?`, `car.hatchback?`, `car.car?`, `car.motorcycle?`.
+    # `pickup?`/`van?` are true whether the term is the kind or the body type.
+    (KINDS | BODY_TYPES).each do |type|
+      define_method("#{type}?") { [@kind, @body_type].include?(type) }
+    end
+
+    def to_h
+      { make: make, model: name, slug: slug, kind: kind, body_type: body_type }
+    end
+
+    # Value-object equality — two models with the same slug are equal.
+    def ==(other)
+      other.is_a?(Model) && other.slug == slug
+    end
+    alias eql? ==
+
+    def hash
+      slug.hash
+    end
+
+    def inspect
+      %(#<Vehicles::Model "#{full_name}" #{body_type}>)
+    end
+
+    # --- Hosted VehiclesDB data (optional) -----------------------------------
+    # These resolve through the provider chain: the hosted API answers when an
+    # api_key is configured, otherwise they degrade to the local data (nil today).
+    # They NEVER raise — a missing/slow API just yields nil and your view renders
+    # a placeholder. See Vehicles::Providers.
+
+    # Production years as a Range, e.g. 1974..2024. nil without hosted data.
+    def years
+      Vehicles.resolve(:years, self)
+    end
+
+    # Editorial market segment, e.g. :hot_hatch, :supercar. nil without hosted data.
+    def segment
+      Vehicles.resolve(:segment, self)
+    end
+
+    # Image URL, optionally year-/color-accurate. nil without hosted data.
+    def image(year: nil, color: nil)
+      Vehicles.resolve(:image, self, year: year, color: color)
+    end
+  end
+end

data/lib/vehicles/providers/hosted_provider.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Vehicles
+  module Providers
+    # Talks to the hosted VehiclesDB API to enrich models with years, images, and
+    # segments. It is STRICTLY OPTIONAL: `available?` is true only when an api_key
+    # is configured, so a key-less install never reaches the network. Every call
+    # is error-isolated — a slow, missing, or failing API yields nil and the
+    # resolver falls back to the local data. Tracking/enrichment must never break
+    # the host app, so this never raises out.
+    #
+    # NOTE: the public VehiclesDB API is not live yet. This is the wired-up seam:
+    # the moment the service ships (and you set `config.api_key`), these methods
+    # light up with zero code changes on the consumer's side. Until then they
+    # safely return nil. Endpoint shape is provisional — see https://vehiclesdb.com.
+    module HostedProvider
+      module_function
+
+      def available?
+        !Vehicles.configuration.api_key.to_s.empty?
+      end
+
+      def years(model)
+        data = fetch(model)
+        return nil unless data && data["year_start"]
+
+        (data["year_start"]..data["year_end"]) # year_end may be nil => endless range
+      end
+
+      def segment(model)
+        fetch(model)&.dig("segment")&.to_sym
+      end
+
+      def image(model, year:, color:)
+        params = {}
+        params[:year]  = year  if year
+        params[:color] = color if color
+        get("/v1/models/#{model.slug}/image", params)&.dig("url")
+      end
+
+      # --- internals -----------------------------------------------------------
+
+      # Fetch + memoize the full model payload for this process. Keyed by slug.
+      def fetch(model)
+        @cache ||= {}
+        return @cache[model.slug] if @cache.key?(model.slug)
+
+        @cache[model.slug] = get("/v1/models/#{model.slug}", {})
+      end
+
+      def reset!
+        @cache = {}
+      end
+
+      # Issue a GET and parse JSON. Returns nil on ANY failure (network, timeout,
+      # non-200, bad JSON) — callers treat nil as "fall back to local data".
+      def get(path, params)
+        # Lazy-required: the gem is standalone-first, and this whole module is
+        # inert without an api_key, so we don't pay net/http at load time.
+        require "net/http"
+        require "uri"
+
+        config = Vehicles.configuration
+        uri = URI.join(config.api_base_url, path)
+        uri.query = URI.encode_www_form(params) unless params.empty?
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = config.api_timeout
+        http.read_timeout = config.api_timeout
+
+        request = Net::HTTP::Get.new(uri)
+        request["Authorization"] = "Bearer #{config.api_key}"
+        request["Accept"] = "application/json"
+
+        response = http.request(request)
+        return nil unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body)
+      rescue StandardError => e
+        warn "[vehicles] hosted lookup failed (#{e.class}); using local data" if $DEBUG
+        nil
+      end
+    end
+  end
+end