showroom 0.1.0

data/README.md

@@ -0,0 +1,200 @@
+# Showroom
+
+A Ruby gem wrapping Shopify's public, unauthenticated JSON endpoints — no app, no token, no session required.
+
+```ruby
+Showroom.configure { |c| c.store = 'acme.myshopify.com' }
+
+Showroom::Product.where(limit: 5).each { |p| puts "#{p.title} — #{p.variants.first.price}" }
+Showroom::Product.find('my-bike').available?
+Showroom::Product.all.first(100)
+```
+
+## Installation
+
+```sh
+gem install showroom
+```
+
+Or in your Gemfile:
+
+```ruby
+gem 'showroom'
+```
+
+## Configuration
+
+### Single-store (module-level)
+
+```ruby
+Showroom.configure do |c|
+  c.store            = 'acme.myshopify.com'   # required
+  c.per_page         = 50                      # default, max 250
+  c.pagination_depth = 50                      # max pages for .all / each_page
+  c.timeout          = 30                      # seconds
+  c.open_timeout     = 10                      # seconds
+  c.user_agent       = 'MyApp/1.0'             # optional override
+end
+```
+
+All options can also be set via environment variables:
+
+| Variable                | Key                |
+|-------------------------|--------------------|
+| `SHOWROOM_STORE`        | `store`            |
+| `SHOWROOM_USER_AGENT`   | `user_agent`       |
+| `SHOWROOM_PER_PAGE`     | `per_page`         |
+| `SHOWROOM_TIMEOUT`      | `timeout`          |
+| `SHOWROOM_OPEN_TIMEOUT` | `open_timeout`     |
+
+### Multi-store (per-client instances)
+
+```ruby
+acme     = Showroom::Client.new(store: 'acme.myshopify.com')
+globo    = Showroom::Client.new(store: 'globo.myshopify.com')
+
+acme.products(limit: 5).map(&:title)
+globo.product('road-bike').price
+```
+
+## Products
+
+```ruby
+# List (single page)
+Showroom::Product.where(limit: 10, product_type: 'Road Bike')
+
+# Single
+product = Showroom::Product.find('lorem-road-bike')
+product.title          # => "Lorem Road Bike"
+product.handle         # => "lorem-road-bike"
+product.vendor         # => "Lorem Cycles"
+product.available?     # => true  (any variant in stock)
+product.price          # => "749.00"  (lowest variant price)
+product.price_range    # => "749.00–899.00"
+product.featured_image # => #<Showroom::ProductImage ...>
+
+# Variants
+product.variants.each do |v|
+  puts "#{v.title}  #{v.price}  on_sale=#{v.on_sale?}  available=#{v.available?}"
+end
+
+# All pages — returns an Enumerator
+Showroom::Product.all.each { |p| puts p.title }
+
+# Explicit page iteration
+Showroom::Product.each_page(limit: 250) do |batch, page|
+  puts "Page #{page}: #{batch.size} products"
+end
+```
+
+### Module-level shortcuts
+
+```ruby
+Showroom.products(limit: 5)      # => Array<Product>
+Showroom.product('lorem-road-bike') # => Product
+```
+
+## Search
+
+Showroom wraps Shopify's `/search/suggest.json` endpoint via `Showroom.search`.
+
+```ruby
+result = Showroom.search('road bike', types: [:product, :collection], limit: 5)
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `q` (first arg) | String | — | Search query |
+| `types:` | Array\<Symbol\> | `[:product, :collection]` | Resource types to include |
+| `limit:` | Integer | `per_page` config | Max results per type |
+
+Available `types:` values: `:product`, `:collection`, `:page`, `:article`, `:query`.
+
+### Accessing results
+
+```ruby
+result = Showroom.search('lorem', types: [:product, :collection, :page, :article, :query])
+
+result.products     # => Array<Search::ProductSuggestion>
+result.collections  # => Array<Search::CollectionSuggestion>
+result.pages        # => Array<Search::PageSuggestion>
+result.articles     # => Array<Search::ArticleSuggestion>
+result.queries      # => Array<Search::QuerySuggestion>
+
+result.products.first.title  # => "Lorem Road Bike"
+result.queries.first.text    # => "lorem road bike"
+```
+
+### Loading full models
+
+Product and collection suggestions expose a `#load` method that fetches the complete model record:
+
+```ruby
+suggestion = result.products.first
+product = suggestion.load  # => Showroom::Product (full record, makes one HTTP request)
+
+suggestion = result.collections.first
+collection = suggestion.load  # => Showroom::Collection
+
+# Page, article, and query suggestions do not support #load
+result.pages.first.load  # => NoMethodError
+```
+
+## Error handling
+
+```ruby
+begin
+  Showroom::Product.find('does-not-exist')
+rescue Showroom::NotFound => e
+  puts "404: #{e.message}"
+rescue Showroom::TooManyRequests
+  puts "Rate limited — back off and retry"
+rescue Showroom::InvalidResponse
+  puts "Store may be password-protected or blocking requests"
+rescue Showroom::ConnectionError
+  puts "Network error"
+rescue Showroom::Error => e
+  puts "Other Showroom error: #{e}"
+end
+```
+
+### Error hierarchy
+
+```
+Showroom::Error
+├── ConfigurationError     bad or missing store URL
+├── ConnectionError        network failure, timeout
+├── InvalidResponse        200 OK but body is HTML (password-protected store)
+└── ResponseError          HTTP status >= 400
+    ├── ClientError        4xx
+    │   ├── BadRequest     400
+    │   ├── NotFound       404
+    │   ├── UnprocessableEntity  422
+    │   └── TooManyRequests     429
+    └── ServerError        5xx
+```
+
+## Custom middleware
+
+```ruby
+Showroom.configure do |c|
+  c.store      = 'acme.myshopify.com'
+  c.middleware = ->(conn) {
+    conn.response :logger
+  }
+end
+```
+
+## Caveats
+
+- **Password-protected stores** return `200 OK` with an HTML body. Showroom raises `InvalidResponse` in this case.
+- **Rate limits** — Shopify's public endpoints allow roughly 2 req/s per IP. Showroom raises `TooManyRequests` (429) but does not retry automatically. Add your own back-off logic.
+- **`/products.json` may be disabled** on some stores. You'll receive a `NotFound` or `ServerError`.
+- **User-Agent** — some stores block the default Faraday UA. Showroom sets its own identifying header by default; override via `c.user_agent` if needed.
+- **Search result ordering is not stable** — `/search/suggest.json` does not guarantee a consistent order across requests. Results with equal relevance scores may alternate non-deterministically. Do not rely on `result.products.first` being the same between calls.
+
+## License
+
+[GNU General Public License v3.0 or later](LICENSE).

data/lib/showroom/client.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative 'core/configurable'
+require_relative 'core/connection'
+require_relative 'models'
+
+module Showroom
+  # A configured HTTP client for a single Showroom store.
+  #
+  # Combines {Core::Configurable} (configuration DSL) with
+  # {Core::Connection} (Faraday-based HTTP).
+  #
+  # @example Single-store usage
+  #   client = Showroom::Client.new(store: 'example.myshopify.com')
+  #   client.get('/products.json', limit: 10)
+  #
+  # @example Multi-store usage
+  #   eu_client = Showroom::Client.new(store: 'eu.shop.com')
+  #   us_client = Showroom::Client.new(store: 'us.shop.com')
+  class Client
+    include Core::Configurable
+    include Core::Connection
+
+    # Initializes a new Client with the given options.
+    #
+    # Resets all keys to defaults first, then applies any provided options.
+    #
+    # @param opts [Hash] configuration overrides (keys from {Core::Configurable::KEYS})
+    # @option opts [String] :store the Shopify store domain or URL
+    # @option opts [String] :user_agent custom User-Agent string
+    # @option opts [Integer] :per_page results per page (clamped to MAX_PER_PAGE)
+    # @option opts [Integer] :pagination_depth maximum pages to fetch
+    # @option opts [Integer] :open_timeout connection timeout in seconds
+    # @option opts [Integer] :timeout read timeout in seconds
+    # @option opts [#call, nil] :middleware Faraday middleware proc
+    # @option opts [Hash] :connection_options extra Faraday connection options
+    def initialize(**opts)
+      reset!
+      opts.each { |key, value| send(:"#{key}=", value) }
+    end
+
+    # Fetches products from the store.
+    #
+    # @param params [Hash] Shopify query parameters
+    # @return [Array<Product>]
+    def products(**params)
+      get('/products.json', params).fetch('products', []).map { |h| Product.new(h) }
+    end
+
+    # Fetches a single product by handle.
+    #
+    # @param handle [String] the product handle
+    # @return [Product]
+    # @raise [Showroom::NotFound] when the product is not found
+    def product(handle)
+      get("/products/#{handle}.json")
+        .fetch('product') { raise Showroom::NotFound, handle }
+        .then { |h| Product.new(h) }
+    end
+
+    # Fetches collections from the store.
+    #
+    # @param params [Hash] Shopify query parameters
+    # @return [Array<Collection>]
+    def collections(**params)
+      get('/collections.json', params).fetch('collections', []).map { |h| Collection.new(h) }
+    end
+
+    # Fetches a single collection by handle.
+    #
+    # @param handle [String] the collection handle
+    # @return [Collection]
+    # @raise [Showroom::NotFound] when the collection is not found
+    def collection(handle)
+      get("/collections/#{handle}.json")
+        .fetch('collection') { raise Showroom::NotFound, handle }
+        .then { |h| Collection.new(h) }
+    end
+
+    # Calls the Shopify search suggest endpoint and returns a {Search::Result}.
+    #
+    # @param query_str [String] the search query
+    # @param types [Array<Symbol>] resource types to search (e.g. +:product+, +:collection+)
+    # @param limit [Integer] maximum results per type (defaults to {#per_page})
+    # @param params [Hash] additional query parameters forwarded to the API
+    # @return [Search::Result]
+    def search(query_str, types: %i[product collection], limit: per_page, **params)
+      query = { q: query_str, 'resources[limit]' => limit }
+      query['resources[type]'] = types.join(',') unless types.empty?
+      query.merge!(params)
+      raw = get('/search/suggest.json', query)
+      Search::Result.new(raw.dig('resources', 'results') || {})
+    end
+  end
+end

data/lib/showroom/core/configurable.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative 'default'
+
+module Showroom
+  module Core
+    # Mixin that provides configuration DSL for the Showroom module and Client.
+    #
+    # When extended into a module or class it adds `configure`, `reset!`,
+    # `options`, and `same_options?`, plus individual key accessors.
+    #
+    # @example Module-level usage
+    #   Showroom.configure do |c|
+    #     c.store = 'example.myshopify.com'
+    #   end
+    module Configurable
+      # Ordered list of all supported configuration keys.
+      KEYS = %i[
+        store
+        user_agent
+        per_page
+        pagination_depth
+        open_timeout
+        timeout
+        middleware
+        connection_options
+        debug
+      ].freeze
+
+      # @!method store
+      #   @return [String, nil]
+      # @!method store=(value)
+      #   @param value [String, nil]
+      # (Similar accessors exist for all KEYS.)
+      KEYS.each { |key| attr_accessor key }
+
+      # Yields self for block-style configuration.
+      #
+      # @yield [self]
+      # @return [self]
+      def configure
+        yield self
+        self
+      end
+
+      # Resets all keys to their defaults from {Default}.
+      #
+      # @return [void]
+      def reset!
+        KEYS.each { |key| send(:"#{key}=", Default.public_send(key)) }
+      end
+
+      # Returns a frozen hash snapshot of the current configuration.
+      #
+      # @return [Hash{Symbol => Object}]
+      def options
+        KEYS.to_h { |key| [key, send(key)] }.freeze
+      end
+
+      # Returns true when +other_options+ matches the current configuration.
+      #
+      # @param other_options [Hash]
+      # @return [Boolean]
+      def same_options?(other_options)
+        options == other_options
+      end
+
+      # Clamps per_page so it never exceeds {Default::MAX_PER_PAGE}.
+      #
+      # @param value [Integer]
+      # @return [void]
+      def per_page=(value)
+        @per_page = [value.to_i, Default::MAX_PER_PAGE].min
+      end
+    end
+  end
+end

data/lib/showroom/core/connection.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module Showroom
+  module Core
+    # Mixin that provides HTTP connectivity via Faraday.
+    #
+    # Expects the including class to expose configuration keys from
+    # {Configurable}: +store+, +user_agent+, +open_timeout+, +timeout+,
+    # +middleware+, and +connection_options+.
+    module Connection
+      # @return [Faraday::Response, nil] the last HTTP response object
+      attr_reader :last_response
+
+      # Memoized Faraday connection built from the current configuration.
+      #
+      # @return [Faraday::Connection]
+      def agent
+        @agent ||= build_agent
+      end
+
+      # Performs a GET request and returns the parsed response body.
+      #
+      # @param path [String] path relative to the store base URL
+      # @param params [Hash] query parameters
+      # @return [Object] parsed JSON body (Hash or Array)
+      def get(path, params = {})
+        puts "GET #{path} with params #{params}" if Showroom.debug
+        @last_response = agent.get(path, params)
+        @last_response.body
+      end
+
+      # Iterates through paginated responses, yielding each page of items.
+      #
+      # Stops when a page returns an empty array or +pagination_depth+ is
+      # reached.
+      #
+      # @param path [String] path relative to the store base URL
+      # @param key [String] top-level JSON key containing the items array
+      # @param params [Hash] base query parameters (page/limit are added automatically)
+      # @yield [items, page] items on the current page and the page number
+      # @yieldparam items [Array] the deserialized items for this page
+      # @yieldparam page [Integer] 1-based page number
+      # @return [void]
+      def paginate(path, key, params = {}, max_pages: pagination_depth, &blk)
+        page_limit = per_page
+
+        (1..max_pages).each do |page|
+          paged_params = params.merge(limit: page_limit, page: page)
+          body         = get(path, paged_params)
+          items        = body.is_a?(Hash) ? body[key] || body[key.to_s] : body
+
+          break if items.nil? || items.empty?
+
+          blk.call(items, page)
+        end
+      end
+
+      private
+
+      # Builds and returns a new Faraday connection.
+      #
+      # @return [Faraday::Connection]
+      def build_agent
+        base = StoreUrl.resolve(store)
+        opts = (connection_options || {}).merge(url: base)
+        Faraday.new(opts) do |conn|
+          configure_conn(conn)
+          middleware&.call(conn)
+        end
+      end
+
+      # Applies default headers, timeouts, and middleware to +conn+.
+      #
+      # @param conn [Faraday::Connection]
+      # @return [void]
+      def configure_conn(conn)
+        conn.headers['User-Agent'] = user_agent
+        conn.options.open_timeout  = open_timeout
+        conn.options.timeout       = timeout
+        conn.use Http::Middleware::RaiseError
+        conn.response :json, content_type: /\bjson\b/, parser_options: { symbolize_names: false }
+        conn.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/showroom/core/countable.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Showroom
+  module Core
+    # Mixin that adds {#calculate_count} to model classes exposing a paginated
+    # index endpoint.
+    #
+    # Uses an exponential probe followed by binary search to locate the last
+    # non-empty page, then derives the total count. Costs O(log n) HTTP
+    # requests where n is the number of pages.
+    #
+    # The count is **approximate** — items may be added or removed between
+    # requests.
+    #
+    # @example
+    #   Product.calculate_count    # => 2847  (O(log n) requests)
+    #   Collection.calculate_count # => 42
+    module Countable
+      MAX_PER_PAGE  = 250
+      MAX_PAGE      = 100
+      MAX_COUNT     = MAX_PER_PAGE * MAX_PAGE # 25_000
+
+      # Estimates the total number of items via binary search over pages.
+      #
+      # Shopify's public endpoints reject page numbers above 100, so the
+      # maximum reportable count is **25,000** (100 pages × 250 per page).
+      # Stores with more items will return 25,000. Any +limit:+ key in
+      # +params+ is ignored — the probe always uses +MAX_PER_PAGE+ (250).
+      #
+      # @param params [Hash] additional query parameters forwarded to the
+      #   index endpoint (e.g. +product_type:+, +vendor:+). +limit:+ is ignored.
+      # @return [Integer] approximate total item count, capped at 25,000
+      def calculate_count(**params)
+        fetch = ->(page) { page_size(page, **params.except(:limit)) }
+        upper = probe_upper_bound(fetch)
+        return 0 if upper == 1 && fetch.call(1).zero?
+
+        tally(fetch, upper)
+      end
+
+      private
+
+      def tally(fetch, upper)
+        result = binary_search(fetch, upper / 2, upper)
+        total  = (result[:lower] * MAX_PER_PAGE) + (result[:upper_size] || fetch.call(result[:upper]))
+        if total >= MAX_COUNT
+          warn "[Showroom] calculate_count hit the #{MAX_COUNT} item ceiling — the store likely has more."
+        end
+        total
+      end
+
+      def probe_upper_bound(fetch)
+        upper = 1
+        upper = [upper * 2, MAX_PAGE].min while fetch.call(upper) == MAX_PER_PAGE && upper < MAX_PAGE
+        upper
+      end
+
+      def binary_search(fetch, lower, upper)
+        upper_size = nil
+        lower, upper, upper_size = binary_search_step(fetch, lower, upper) while lower < upper - 1
+        { lower: lower, upper: upper, upper_size: upper_size }
+      end
+
+      def binary_search_step(fetch, lower, upper)
+        mid  = (lower + upper) / 2
+        size = fetch.call(mid)
+        size == MAX_PER_PAGE ? [mid, upper, nil] : [lower, mid, size]
+      end
+
+      def page_size(page, **params)
+        body  = Showroom.client.get(index_path, params.merge(limit: MAX_PER_PAGE, page: page))
+        items = body.is_a?(Hash) ? body[index_key] : body
+        items&.size || 0
+      rescue Showroom::BadRequest
+        0
+      end
+    end
+  end
+end

data/lib/showroom/core/default.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Showroom
+  module Core
+    # Provides default configuration values for the gem, with optional
+    # overrides via environment variables.
+    module Default
+      # Maximum allowed value for per_page.
+      MAX_PER_PAGE = 250
+
+      # @return [nil] store is required and has no default
+      def self.store
+        ENV.fetch('SHOWROOM_STORE', nil)
+      end
+
+      # @return [String] default User-Agent header value
+      def self.user_agent
+        ENV.fetch(
+          'SHOWROOM_USER_AGENT',
+          "Showroom/#{VERSION} (+https://github.com/01max/showroom; Ruby/#{RUBY_VERSION})"
+        )
+      end
+
+      # @return [Integer] number of results per page, clamped to MAX_PER_PAGE
+      def self.per_page
+        raw = ENV.fetch('SHOWROOM_PER_PAGE', MAX_PER_PAGE).to_i
+        [raw, MAX_PER_PAGE].min
+      end
+
+      # @return [Integer] maximum number of pages to fetch during pagination
+      def self.pagination_depth
+        50
+      end
+
+      # @return [Integer] open (connect) timeout in seconds
+      def self.open_timeout
+        ENV.fetch('SHOWROOM_OPEN_TIMEOUT', 10).to_i
+      end
+
+      # @return [Integer] read timeout in seconds
+      def self.timeout
+        ENV.fetch('SHOWROOM_TIMEOUT', 30).to_i
+      end
+
+      # @return [nil] no custom middleware by default
+      def self.middleware
+        nil
+      end
+
+      # @return [Hash] extra options passed to Faraday connection
+      def self.connection_options
+        {}
+      end
+
+      # @return [Boolean] whether to print debug output for each request
+      def self.debug # rubocop:disable Naming/PredicateMethod
+        ENV.fetch('SHOWROOM_DEBUG', nil) == '1'
+      end
+    end
+  end
+end

data/lib/showroom/core/error.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Showroom
+  # Base error class for all Showroom errors.
+  class Error < StandardError; end
+
+  # Raised when the gem is misconfigured (e.g. missing or invalid store URL).
+  class ConfigurationError < Error; end
+
+  # Raised when a network-level failure occurs (connection refused, timeout, etc.).
+  class ConnectionError < Error; end
+
+  # Raised when the response body is not JSON (e.g. store is password-protected).
+  class InvalidResponse < Error; end
+
+  # Raised for HTTP responses with status >= 400.
+  #
+  # @attr_reader status [Integer] HTTP status code
+  # @attr_reader body [String, nil] raw response body
+  # @attr_reader headers [Hash] response headers
+  class ResponseError < Error
+    attr_reader :status, :body, :headers
+
+    # @param message [String] error message
+    # @param status [Integer] HTTP status code
+    # @param body [String, nil] raw response body
+    # @param headers [Hash] response headers
+    def initialize(message = nil, status: nil, body: nil, headers: {})
+      super(message || "HTTP #{status}")
+      @status  = status
+      @body    = body
+      @headers = headers
+    end
+  end
+
+  # Raised for HTTP 4xx responses.
+  class ClientError < ResponseError; end
+
+  # Raised for HTTP 400 Bad Request.
+  class BadRequest < ClientError; end
+
+  # Raised for HTTP 404 Not Found.
+  class NotFound < ClientError; end
+
+  # Raised for HTTP 422 Unprocessable Entity.
+  class UnprocessableEntity < ClientError; end
+
+  # Raised for HTTP 429 Too Many Requests.
+  class TooManyRequests < ClientError; end
+
+  # Raised for HTTP 5xx responses.
+  class ServerError < ResponseError; end
+end