Showroom

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)

gem 'showroom'

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

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

# Models remember which client fetched them
product = acme.product('lorem-road-bike')
product.url  # => "https://acme.myshopify.com/products/lorem-road-bike"

# base_url is available on any client
acme.base_url  # => "https://acme.myshopify.com"

# 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 | false | nil  (nil when no variant exposes availability)
product.availability_known? # => true when availability can be determined
product.price               # => "749.00"  (lowest variant price)
product.price_range    # => "749.00–899.00"
product.prices         # => ["749.00", "899.00"]  (unique prices from all variants)
product.url            # => "https://acme.myshopify.com/products/lorem-road-bike"
product.featured_image # => #<Showroom::ProductImage ...>  (first image)
product.main_image     # => #<Showroom::ProductImage ...>  (image with position 1)

# Similar products — searches by handle (SKU fragments stripped), falls back to title
product.similar                          # => Array<Search::ProductSuggestion>, sorted by price
product.similar(limit: 3)               # forward any Client#search keyword
product.similar.first.load              # => Showroom::Product (full record)

# Variants
product.variants.each do |v|
  puts "#{v.title}  #{v.price}  #{v.compare_at_price}  on_sale=#{v.on_sale?}  available=#{v.available?}  availability_known=#{v.availability_known?}"
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

Showroom.products(limit: 5)      # => Array<Product>
Showroom.product('lorem-road-bike') # => Product

# List
Showroom::Collection.where(limit: 10)

# Single
collection = Showroom::Collection.find('lorem-helmets')
collection.title          # => "Lorem Helmets"
collection.handle         # => "lorem-helmets"
collection.products_count # => 12
collection.url            # => "https://acme.myshopify.com/collections/lorem-helmets"

# Products in a collection
collection.products(limit: 5).each { |p| puts p.title }

Showroom.collections(limit: 5)          # => Array<Collection>
Showroom.collection('lorem-helmets')    # => Collection

result = Showroom.search('road bike', types: [:product, :collection], limit: 5)

result = Showroom.search('lorem', types: [:product, :collection, :page, :article, :query])

result.products     # => Array<Search::ProductSuggestion>  (API order)
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"

# Sort product suggestions client-side
result.products(order: :price)   # numeric ascending
result.products(order: :title)   # alphabetical
result.products(order: :handle)  # alphabetical
result.products(order: :id)      # numeric ascending
# Accepted values: :id, :title, :handle, :price — raises ArgumentError otherwise

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

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

Showroom.configure do |c|
  c.store      = 'acme.myshopify.com'
  c.middleware = ->(conn) {
    conn.response :logger
  }
end