adadiamonds 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a6bdae7ac7a99d8a70ee8800eec58b6692a35c63784cad85e75b835398857b6
+  data.tar.gz: 47f5cc02e53554e5326781a9645914403b4d47f0b8a464c4896459fccf2b43c1
+SHA512:
+  metadata.gz: 669e2711d23848bf585a0a6b3f6f6e26f8f5114e4759b5f7cee63a185164c9731d83f8583b09c6796f630b9de11f69fc4a616bc6bd7a4b2b68c9043b99098a3e
+  data.tar.gz: 37e2e2ed149551590cfa04ae8cc62e4d6d8765c3633ae2f05490b111619064134449f640300297024da48bac9e72b1070746d3076d58b87f1a2e2e27ad66a0b2

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- First release: `AdaDiamonds::Client` with one method per endpoint (`diamonds`, `diamond`, `engagement_rings`, `engagement_ring`, `jewelry`, `jewelry_item`, `knowledge_base`, `article`, `showrooms`, `request_consultation`, `create_key`, `batch`, `ask`), generic `get`/`post`, `AdaDiamonds::Error`, and `last_rate_limit`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ada Diamonds, Inc.
+
+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,112 @@
+# adadiamonds
+
+Official Ruby client for the [Ada Diamonds](https://www.adadiamonds.com) API: live lab grown diamond inventory, engagement ring settings, fine jewelry, showrooms, and the diamond buying guides.
+
+Standard library only (`net/http`, `json`). Ruby 2.6 or newer.
+
+- Documentation: https://www.adadiamonds.com/developers
+- REST reference: https://www.adadiamonds.com/developers/api
+- OpenAPI 3.1: https://www.adadiamonds.com/openapi.json
+- MCP server (for tool use instead of HTTP): https://www.adadiamonds.com/mcp
+
+## Install
+
+```bash
+gem install adadiamonds
+```
+
+or in a Gemfile:
+
+```ruby
+gem "adadiamonds"
+```
+
+Reading the catalog needs no account and no API key (120 requests per minute). An API key raises that to 600 and unlocks the write endpoints. Every price is in US dollars.
+
+## Examples
+
+### Search live diamond inventory
+
+```ruby
+require "adadiamonds"
+
+client = AdaDiamonds::Client.new # anonymous
+page = client.diamonds(shape: "Oval", min_carat: 1, max_price: 4000, sort: "price_asc")
+page.each do |stone|
+  puts [stone["carat"], stone["shape"], stone["price"]].join(" ")
+end
+p client.last_rate_limit # #<struct limit=120, remaining=119, reset=58, policy="...">
+```
+
+### Quote a complete ring
+
+An engagement ring is a setting plus a loose diamond, priced separately. Setting prices never include the center stone.
+
+```ruby
+setting = client.engagement_rings(shape: "Oval", type: "Solitaire", limit: 1).first
+stone = client.diamonds(shape: "Oval", min_carat: 1.5, max_carat: 1.6, sort: "price_asc", limit: 1).first
+puts setting["priceFrom"] + stone["price"] # US dollars
+```
+
+### Authenticate and write
+
+```ruby
+key = AdaDiamonds::Client.new.create_key("my-agent", env: "sandbox")
+client = AdaDiamonds::Client.new(api_key: key["api_key"]) # 600 requests/min
+
+begin
+  client.request_consultation(
+    { "email" => "test@example.com", "topic" => "engagement_ring" },
+    idempotency_key: "consult-42" # a retry cannot create two requests
+  )
+rescue AdaDiamonds::Error => e
+  puts [e.status, e.code, e.description, e.retry_after].inspect
+end
+```
+
+Sandbox keys (`ada_test_*`) return well-formed responses and contact nobody.
+
+### Ask a question (NLWeb)
+
+```ruby
+answer = client.ask("oval lab diamond engagement ring under $6,000")
+```
+
+### Anything else
+
+Every method maps to one endpoint under `/api/v1`. For endpoints without a helper, `get` and `post` take a path relative to `/api/v1` (or absolute on the site) and return the decoded JSON:
+
+```ruby
+bands = client.get("/jewelry", category: "wedding-bands")
+```
+
+## Methods
+
+| Method | Endpoint |
+| --- | --- |
+| `diamonds`, `diamond` | `GET /api/v1/diamonds`, `GET /api/v1/diamonds/{id}` |
+| `engagement_rings`, `engagement_ring` | `GET /api/v1/engagement-rings`, `.../{slug}` |
+| `jewelry`, `jewelry_item` | `GET /api/v1/jewelry`, `.../{slug}` |
+| `knowledge_base`, `article` | `GET /api/v1/knowledge-base`, `.../{slug}` |
+| `showrooms` | `GET /api/v1/showrooms` |
+| `request_consultation` | `POST /api/v1/consultations` |
+| `create_key` | `POST /api/v1/keys` |
+| `batch` | `POST /api/v1/batch` (up to 20 GETs in one round trip) |
+| `ask` | `GET /ask` (NLWeb) |
+
+List methods return an `AdaDiamonds::Page` (`data`, `pagination`, `total`, `has_more?`, and `Enumerable`). Errors are `AdaDiamonds::Error` with `status`, `code`, `description`, `documentation_url`, and `retry_after`. Every response's `RateLimit-*` headers are available from `last_rate_limit`; pace yourself rather than retrying into a 429.
+
+## Etiquette
+
+Identify your agent with `AdaDiamonds::Client.new(user_agent: "my-agent/1.0 (+https://example.com)")`. Bulk scraping of the HTML catalog is not permitted; this API and `POST /api/v1/exports` are the supported way to read it. Diamond inventory changes continuously; re-check a stone before quoting it.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT. Copyright Ada Diamonds, Inc.

data/lib/adadiamonds/client.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+module AdaDiamonds
+  # Production host.
+  DEFAULT_BASE_URL = "https://www.adadiamonds.com"
+  # REST API version this client targets.
+  API_VERSION = "v1"
+  USER_AGENT = "ada-diamonds-ruby/#{VERSION} (+https://www.adadiamonds.com/developers)"
+
+  # Site-root endpoints that do not live under /api/v1.
+  ROOT_PATHS = ["/ask", "/mcp", "/openapi.json", "/llms.txt"].freeze
+
+  # A non-2xx response, decoded from the API's JSON error body: a stable
+  # machine-readable +code+, a human-readable +description+ that says what to
+  # do next, and the HTTP +status+. +documentation_url+ and +retry_after+
+  # (seconds) are carried when the API sends them.
+  class Error < StandardError
+    attr_reader :status, :code, :description, :documentation_url, :retry_after, :body
+
+    def initialize(status:, code:, description: "", documentation_url: nil, retry_after: 0, body: {})
+      @status = status
+      @code = code
+      @description = description
+      @documentation_url = documentation_url
+      @retry_after = retry_after
+      @body = body
+      super(description.empty? ? "#{status} #{code}" : "#{status} #{code}: #{description}")
+    end
+  end
+
+  # The RateLimit-* headers from the most recent response. Counters are per
+  # 60 second window; treat them as a pacing signal.
+  RateLimit = Struct.new(:limit, :remaining, :reset, :policy, keyword_init: true)
+
+  # One page of a list response: catalog items plus pagination. Items are
+  # plain hashes because the catalog schema evolves faster than a client
+  # release; the field names match the OpenAPI document exactly.
+  class Page
+    include Enumerable
+
+    attr_reader :object, :currency, :data, :pagination
+
+    def initialize(body)
+      body ||= {}
+      @object = body["object"]
+      @currency = body["currency"]
+      @data = body["data"] || []
+      @pagination = body["pagination"] || {}
+    end
+
+    def each(&block)
+      @data.each(&block)
+    end
+
+    def total
+      @pagination["total"]
+    end
+
+    def limit
+      @pagination["limit"]
+    end
+
+    def offset
+      @pagination["offset"]
+    end
+
+    def has_more?
+      @pagination["has_more"] == true
+    end
+  end
+
+  # Calls the Ada Diamonds REST API. Every public method maps to exactly one
+  # endpoint; anything the client does can be reproduced with curl.
+  class Client
+    attr_reader :base_url, :api_key, :user_agent, :timeout, :last_rate_limit, :last_headers
+
+    # +api_key+: an ada_live_* / ada_test_* key or an OAuth access token (nil
+    # means anonymous). +base_url+ points at another host (a staging
+    # deployment, a proxy). +user_agent+ identifies your agent.
+    def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, user_agent: USER_AGENT, timeout: 30)
+      @api_key = api_key
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @user_agent = user_agent
+      @timeout = timeout
+      @last_rate_limit = nil
+      @last_headers = {}
+    end
+
+    # ---------------------------------------------------------------- catalog
+
+    # Searches available loose lab grown diamonds. Filters: shape, min_carat,
+    # max_carat, min_price, max_price, color, clarity, cut, sort (price_asc |
+    # price_desc | carat_asc | carat_desc), limit, offset.
+    def diamonds(params = {})
+      Page.new(get("/diamonds", params))
+    end
+
+    # Fetches one stone by id (the catalog id or grading report number).
+    def diamond(id)
+      get("/diamonds/#{escape(id)}")
+    end
+
+    # Searches ring settings. Filters: shape, style, type, min_price,
+    # max_price, q, limit, offset. Setting prices exclude the center stone.
+    def engagement_rings(params = {})
+      Page.new(get("/engagement-rings", params))
+    end
+
+    # Fetches one setting by slug.
+    def engagement_ring(slug)
+      get("/engagement-rings/#{escape(slug)}")
+    end
+
+    # Searches wedding bands, earrings, necklaces, bracelets, and fashion
+    # rings. Filters: category, type, shape, min_price, max_price, q, limit, offset.
+    def jewelry(params = {})
+      Page.new(get("/jewelry", params))
+    end
+
+    # Fetches one jewelry product by slug.
+    def jewelry_item(slug)
+      get("/jewelry/#{escape(slug)}")
+    end
+
+    # Lists the buying guides and articles. +query+ may be nil.
+    def knowledge_base(query = nil, params = {})
+      merged = params.dup
+      merged[:q] = query if query && !query.empty?
+      Page.new(get("/knowledge-base", merged))
+    end
+
+    # Fetches one article by slug, with its body as markdown.
+    def article(slug)
+      get("/knowledge-base/#{escape(slug)}")
+    end
+
+    # Lists showroom locations, hours, and remote consultation options.
+    def showrooms
+      get("/showrooms")
+    end
+
+    # ----------------------------------------------------------------- writes
+
+    # Asks a jeweler to contact the customer. Requires the appointments:write
+    # scope (any API key). Sandbox keys return a well-formed response and
+    # contact nobody. Pass an +idempotency_key+ so a retried call cannot
+    # create two requests.
+    def request_consultation(payload, idempotency_key: nil)
+      headers = idempotency_key ? { "Idempotency-Key" => idempotency_key } : {}
+      request(:post, "/consultations", body: payload, headers: headers)
+    end
+
+    # Issues a self-serve API key. +env+ is "sandbox" or "production". The key
+    # is returned once, in the api_key field; only a hash is stored.
+    def create_key(name, env: "sandbox")
+      post("/keys", { name: name, env: env })
+    end
+
+    # Runs up to 20 GET requests in one round trip via POST /api/v1/batch.
+    # Each request is a hash with id, method, path, and an optional query.
+    # The response carries one responses entry per request, in order, each
+    # with its own id, status, and body.
+    def batch(requests)
+      post("/batch", { requests: requests })
+    end
+
+    # ------------------------------------------------------------------ nlweb
+
+    # Sends a natural-language question to the NLWeb /ask endpoint and returns
+    # the JSON answer (products and guides with citations).
+    def ask(query, params = {})
+      get("/ask", params.merge(query: query))
+    end
+
+    # ---------------------------------------------------------------- generic
+
+    # GET any path relative to /api/v1 ("/diamonds") or absolute on the site
+    # ("/ask", "/api/acp/...") and decode the JSON response.
+    def get(path, params = {})
+      request(:get, path, params: params)
+    end
+
+    # POST a JSON body to any path and decode the JSON response.
+    def post(path, body = nil)
+      request(:post, path, body: body)
+    end
+
+    # Sends one request. Returns the decoded JSON (nil for an empty body) or
+    # raises AdaDiamonds::Error for a non-2xx response.
+    def request(method, path, params: {}, body: nil, headers: {})
+      uri = URI(resolve(path))
+      query = encode_params(params)
+      uri.query = [uri.query, query].compact.reject(&:empty?).join("&") unless query.empty?
+
+      klass = method.to_s.upcase == "POST" ? Net::HTTP::Post : Net::HTTP::Get
+      req = klass.new(uri)
+      req["Accept"] = "application/json"
+      req["User-Agent"] = user_agent
+      req["Authorization"] = "Bearer #{api_key}" if api_key && !api_key.empty?
+      headers.each { |k, v| req[k] = v }
+      if body
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      res = http.request(req)
+
+      remember(res)
+      raw = res.body.to_s
+      status = res.code.to_i
+      raise decode_error(status, raw, res) unless (200..299).cover?(status)
+      return nil if status == 204 || raw.strip.empty?
+
+      JSON.parse(raw)
+    end
+
+    private
+
+    def escape(value)
+      URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+    end
+
+    def resolve(path)
+      path = path.to_s
+      return path if path.start_with?("http://", "https://")
+
+      path = "/#{path}" unless path.start_with?("/")
+      bare = path.split("?", 2).first
+      return "#{base_url}#{path}" if path.start_with?("/api/") || ROOT_PATHS.include?(bare)
+
+      "#{base_url}/api/#{API_VERSION}#{path}"
+    end
+
+    # Builds a query string with deterministic key order. Nil and empty-string
+    # values are skipped, so a caller can pass optional filters without pruning
+    # them first. Arrays are repeated as multiple values of the same key.
+    def encode_params(params)
+      return "" if params.nil? || params.empty?
+
+      pairs = []
+      params.keys.map(&:to_s).sort.each do |key|
+        value = params.fetch(key.to_sym) { params[key] }
+        Array(value).each do |item|
+          next if item.nil?
+
+          text = item.to_s
+          next if text.empty?
+
+          pairs << [key, text]
+        end
+      end
+      URI.encode_www_form(pairs)
+    end
+
+    def remember(res)
+      @last_headers = res.each_header.to_h
+      to_i = ->(name) { res[name].to_s.strip.to_i }
+      @last_rate_limit = RateLimit.new(
+        limit: to_i.call("RateLimit-Limit"),
+        remaining: to_i.call("RateLimit-Remaining"),
+        reset: to_i.call("RateLimit-Reset"),
+        policy: res["RateLimit-Policy"].to_s
+      )
+    end
+
+    def decode_error(status, raw, res)
+      code = "http_#{status}"
+      description = ""
+      documentation_url = nil
+      retry_after = 0
+      body = {}
+      parsed = begin
+        raw.empty? ? nil : JSON.parse(raw)
+      rescue JSON::ParserError
+        nil
+      end
+      if parsed.is_a?(Hash)
+        body = parsed
+        code = parsed["error"] if parsed["error"].is_a?(String) && !parsed["error"].empty?
+        description = parsed["error_description"] if parsed["error_description"].is_a?(String)
+        documentation_url = parsed["documentation_url"] if parsed["documentation_url"].is_a?(String)
+        retry_after = parsed["retry_after_seconds"].to_i if parsed["retry_after_seconds"].is_a?(Numeric)
+      elsif !raw.empty?
+        description = raw[0, 500]
+      end
+      retry_after = res["Retry-After"].to_s.strip.to_i if retry_after.zero? && res["Retry-After"]
+      Error.new(status: status, code: code, description: description, documentation_url: documentation_url,
+                retry_after: retry_after, body: body)
+    end
+  end
+end

data/lib/adadiamonds/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module AdaDiamonds
+  # Client version, sent in the User-Agent header.
+  VERSION = "0.1.0"
+end

data/lib/adadiamonds.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Official Ruby client for the Ada Diamonds API: live lab grown diamond
+# inventory, engagement ring settings, fine jewelry, showrooms, and the
+# diamond buying guides.
+#
+# Reading the catalog needs no account and no API key (120 requests per
+# minute). An API key or OAuth access token raises the limit to 600 and
+# unlocks the write endpoints. Every price is in US dollars.
+#
+#   client = AdaDiamonds::Client.new
+#   page = client.diamonds(shape: "Oval", min_carat: 1, max_price: 4000)
+#   page.data.each { |stone| puts [stone["carat"], stone["shape"], stone["price"]].join(" ") }
+#
+# Documentation: https://www.adadiamonds.com/developers
+# OpenAPI: https://www.adadiamonds.com/openapi.json
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "adadiamonds/version"
+require_relative "adadiamonds/client"

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: adadiamonds
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ada Diamonds
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-08-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+description: Search live lab grown diamond inventory, engagement ring settings, fine
+  jewelry, showrooms, and the diamond buying guides at adadiamonds.com. Standard library
+  only; no account or API key needed to read the catalog.
+email:
+- it@adadiamonds.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/adadiamonds.rb
+- lib/adadiamonds/client.rb
+- lib/adadiamonds/version.rb
+homepage: https://www.adadiamonds.com/developers
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.adadiamonds.com/developers
+  documentation_uri: https://www.adadiamonds.com/developers/cli
+  source_code_uri: https://github.com/adadiamonds/ada-ruby
+  changelog_uri: https://github.com/adadiamonds/ada-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/adadiamonds/ada-ruby/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+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: Official Ruby client for the Ada Diamonds API
+test_files: []