vehiclesdb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ddd74fa0a497549ce1320d4859903850c50194a49cd6066f8f085d23fc6b02fb
+  data.tar.gz: bc0cc1609d2f8d7cf129b3f64fb85b99fd2c7d0c7e8a139e6c3580d125c1fac6
+SHA512:
+  metadata.gz: 70fd6c47778a661e5d124aa4cae9507d755758912d9e80a250cbb7545c00e9ef6fcdd97eac6faf83476aef5a04467cc9c78d8944234133c1033e38a7cd2fdb76
+  data.tar.gz: 361c00023f83304dce6106cf0a78528f2473f342e5d090c716292cb53f4facf9b8423d5d375cb71120d443a9738d7326f36bfe67c966be8180b75f124f03abc9

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-23
+
+Initial release — the shell. Reserves the gem and establishes its shape ahead of
+the VehiclesDB API going public.
+
+### Added
+- `VehiclesDB.configure` + `VehiclesDB::Configuration` (api_key — defaults from
+  `ENV["VEHICLESDB_API_KEY"]` — api_base_url, timeout, user_agent).
+- `VehiclesDB::Client` with auth/JSON/timeout request plumbing and a
+  `configured?` check; `VehiclesDB.client` memoized default client.
+- Error hierarchy: `VehiclesDB::Error` < `ConfigurationError` / `AuthenticationError` / `ApiError`.
+
+Resource methods (model, image, …) land as the API ships.
+
+[Unreleased]: https://github.com/rameerez/vehiclesdb-ruby/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/rameerez/vehiclesdb-ruby/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Javi R
+
+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,82 @@
+# 🚗 `vehiclesdb` – Official Ruby SDK for the VehiclesDB API
+
+[![Gem Version](https://badge.fury.io/rb/vehiclesdb.svg)](https://badge.fury.io/rb/vehiclesdb) [![Build Status](https://github.com/rameerez/vehiclesdb-ruby/workflows/Tests/badge.svg)](https://github.com/rameerez/vehiclesdb-ruby/actions)
+
+> [!TIP]
+> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=vehiclesdb)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=vehiclesdb)!
+
+`vehiclesdb` is the official Ruby client for the [**VehiclesDB API**](https://vehiclesdb.com) — a hosted service for rich vehicle data: production years, model images (year- and color-accurate), market segments, specifications, and more.
+
+> [!NOTE]
+> **This is an early shell release.** It reserves the gem and sets its shape; the VehiclesDB API isn't public yet, so resource methods (models, images, …) land as the service ships. Configuration, the client, and the error model are in place today.
+
+## `vehiclesdb` vs `vehicles` — which do I want?
+
+Two gems, one product, and they're **fully independent** (each works on its own):
+
+| | [`vehicles`](https://github.com/rameerez/vehicles) | `vehiclesdb` (this gem) |
+|---|---|---|
+| What | Bundled make/model dataset + a delightful local API | Thin client for the hosted VehiclesDB API |
+| Data | Ships **inside the gem** (EU, offline) | Lives on the **server** (the paid API) |
+| Setup | Zero — no key, no network | Needs an API key |
+| Use it for | Make/model dropdowns, search, validation | Years, images, segments, specs |
+
+Most apps want **`vehicles`** — it works offline with zero config. Add **`vehiclesdb`** (and a key) when you want the richer hosted data; `vehicles` will use it automatically for enrichment. Or use `vehiclesdb` directly if all you want is the raw API.
+
+## Installation
+
+```ruby
+gem "vehiclesdb"
+```
+
+## Usage
+
+```ruby
+VehiclesDB.configure do |config|
+  config.api_key = ENV["VEHICLESDB_API_KEY"]   # or just set ENV["VEHICLESDB_API_KEY"]
+end
+
+VehiclesDB.client.configured?   # => true
+```
+
+You can also build a client explicitly (handy for multiple keys / standalone use):
+
+```ruby
+client = VehiclesDB::Client.new(api_key: "vdb_live_...")
+client.configured?              # => true
+```
+
+### Errors
+
+Everything raises a subclass of `VehiclesDB::Error`, so you can rescue broadly or narrowly:
+
+```ruby
+VehiclesDB::Error             # rescue-all base
+VehiclesDB::ConfigurationError # no API key configured
+VehiclesDB::AuthenticationError # bad key (HTTP 401/403)
+VehiclesDB::ApiError           # other non-2xx — carries #status and #body
+```
+
+## Configuration
+
+| Option | Default | Notes |
+|---|---|---|
+| `api_key` | `ENV["VEHICLESDB_API_KEY"]` | your VehiclesDB key |
+| `api_base_url` | `https://api.vehiclesdb.com` | override for staging/self-host/tests |
+| `timeout` | `5` | request timeout (seconds) |
+| `user_agent` | `vehiclesdb-ruby/<version>` | sent with every request |
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run
+`rake test`. You can also run `bin/console` for an interactive prompt.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/vehiclesdb-ruby. Our code of conduct is: just be nice and make your mom proud of what you do and post online.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/vehiclesdb/client.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module VehiclesDB
+  # A thin client over the VehiclesDB HTTP API. Standalone: construct one
+  # directly, or use `VehiclesDB.client` (which reads the global configuration).
+  #
+  #   client = VehiclesDB::Client.new(api_key: "vdb_...")
+  #   client.configured?   # => true
+  #
+  # The request plumbing (auth header, JSON, timeout, error mapping) is ready;
+  # resource methods (e.g. `model`, `image`) are added as the API ships — they'll
+  # build on the private `get` below. Kept deliberately small for now: this
+  # release reserves the gem and sets the shape.
+  class Client
+    attr_reader :api_key, :api_base_url, :timeout
+
+    def initialize(api_key: nil, api_base_url: nil, timeout: nil)
+      config        = VehiclesDB.configuration
+      @api_key      = api_key      || config.api_key
+      @api_base_url = api_base_url || config.api_base_url
+      @timeout      = timeout      || config.timeout
+    end
+
+    # True when an API key is present (the client can authenticate).
+    def configured?
+      !api_key.to_s.empty?
+    end
+
+    private
+
+    # GET a JSON resource and return the parsed body. Raises ConfigurationError
+    # when unconfigured, AuthenticationError on 401/403, ApiError otherwise. The
+    # caller decides whether to rescue. Resource methods will wrap this.
+    def get(path, params = {})
+      raise ConfigurationError, "No VehiclesDB API key configured" unless configured?
+
+      handle(connection.get(path, params))
+    end
+
+    def handle(response)
+      return response.body if response.success?
+      raise AuthenticationError, "Invalid VehiclesDB API key" if [401, 403].include?(response.status)
+
+      raise ApiError.new("VehiclesDB API error (HTTP #{response.status})",
+                         status: response.status, body: response.body)
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: api_base_url) do |f|
+        f.request :json
+        f.response :json
+        f.headers["Authorization"] = "Bearer #{api_key}"
+        f.headers["User-Agent"] = VehiclesDB.configuration.user_agent
+        f.options.timeout = timeout
+        f.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/vehiclesdb/configuration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module VehiclesDB
+  # Global configuration. Sensible defaults; the API key is picked up from
+  # ENV["VEHICLESDB_API_KEY"] automatically, so the common case needs no setup.
+  #
+  #   VehiclesDB.configure do |config|
+  #     config.api_key = "vdb_live_..."
+  #   end
+  class Configuration
+    # Your VehiclesDB API key. Defaults to ENV["VEHICLESDB_API_KEY"].
+    attr_accessor :api_key
+
+    # Base URL of the API. Overridable for self-hosting / staging / testing.
+    attr_accessor :api_base_url
+
+    # Request timeout in seconds.
+    attr_accessor :timeout
+
+    # Sent as the User-Agent header so VehiclesDB can see SDK usage.
+    attr_accessor :user_agent
+
+    def initialize
+      @api_key      = ENV.fetch("VEHICLESDB_API_KEY", nil)
+      @api_base_url = "https://api.vehiclesdb.com"
+      @timeout      = 5
+      @user_agent   = "vehiclesdb-ruby/#{VehiclesDB::VERSION}"
+    end
+  end
+end

data/lib/vehiclesdb/error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module VehiclesDB
+  # Base class for every error this gem raises — rescue `VehiclesDB::Error` to
+  # catch them all.
+  class Error < StandardError; end
+
+  # No API key configured (or an empty one).
+  class ConfigurationError < Error; end
+
+  # The API rejected the credentials (HTTP 401/403).
+  class AuthenticationError < Error; end
+
+  # Any other non-success API response. Carries the HTTP status and parsed body.
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message)
+    end
+  end
+end

data/lib/vehiclesdb/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module VehiclesDB
+  VERSION = "0.1.0"
+end

data/lib/vehiclesdb.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "vehiclesdb/version"
+require_relative "vehiclesdb/error"
+require_relative "vehiclesdb/configuration"
+require_relative "vehiclesdb/client"
+
+# VehiclesDB — the official Ruby SDK for the VehiclesDB API
+# (https://vehiclesdb.com): a hosted service for rich vehicle data — production
+# years, model images (year- and color-accurate), market segments, specs, and more.
+#
+# This is the low-level API wrapper. If you just want make/model dropdowns that
+# work offline with zero setup, use the `vehicles` gem instead — it bundles the
+# data locally and reaches for VehiclesDB only for optional hosted enrichment.
+# The two are independent: `vehicles` works without this gem, and this gem works
+# without `vehicles`.
+#
+#   VehiclesDB.configure { |c| c.api_key = ENV["VEHICLESDB_API_KEY"] }
+#   VehiclesDB.client.configured?   # => true
+#
+# NOTE: the VehiclesDB API is not public yet. This release reserves the gem and
+# establishes its shape; resource methods land as the API ships.
+module VehiclesDB
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    # Reset config + the memoized default client. Mainly for tests.
+    def reset_configuration!
+      @configuration = Configuration.new
+      @client = nil
+    end
+
+    # Memoized default client, built from the global configuration.
+    def client
+      @client ||= Client.new
+    end
+  end
+end

data/sig/vehiclesdb.rbs

@@ -0,0 +1,41 @@
+# Type signatures for the public API. (Best-effort; the README and code are the
+# source of truth.)
+
+module VehiclesDB
+  VERSION: String
+
+  def self.configuration: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.reset_configuration!: () -> void
+  def self.client: () -> Client
+
+  class Error < StandardError
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class AuthenticationError < Error
+  end
+
+  class ApiError < Error
+    attr_reader status: Integer?
+    attr_reader body: untyped
+    def initialize: (?String?, ?status: Integer?, ?body: untyped) -> void
+  end
+
+  class Configuration
+    attr_accessor api_key: String?
+    attr_accessor api_base_url: String
+    attr_accessor timeout: Integer
+    attr_accessor user_agent: String
+  end
+
+  class Client
+    attr_reader api_key: String?
+    attr_reader api_base_url: String
+    attr_reader timeout: Integer
+    def initialize: (?api_key: String?, ?api_base_url: String?, ?timeout: Integer?) -> void
+    def configured?: () -> bool
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: vehiclesdb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- rameerez
+bindir: bin
+cert_chain: []
+date: 2026-06-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 'vehiclesdb is the official Ruby client for the VehiclesDB API (https://vehiclesdb.com),
+  a hosted service for rich vehicle data: production years, model images (year- and
+  color-accurate), market segments, specifications, and more. It''s the low-level
+  API wrapper that the `vehicles` gem uses for optional hosted enrichment — but both
+  gems are fully independent and usable on their own.'
+email:
+- rubygems@rameerez.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/vehiclesdb.rb
+- lib/vehiclesdb/client.rb
+- lib/vehiclesdb/configuration.rb
+- lib/vehiclesdb/error.rb
+- lib/vehiclesdb/version.rb
+- sig/vehiclesdb.rbs
+homepage: https://github.com/rameerez/vehiclesdb-ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/rameerez/vehiclesdb-ruby
+  source_code_uri: https://github.com/rameerez/vehiclesdb-ruby/tree/main
+  changelog_uri: https://github.com/rameerez/vehiclesdb-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Official Ruby SDK for the VehiclesDB API — rich vehicle data (years, images,
+  segments, specs).
+test_files: []