showroom 0.1.0

data/lib/showroom/core/store_url.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Showroom
+  module Core
+    # Resolves a raw store identifier into a canonical HTTPS base URL.
+    module StoreUrl
+      # Resolves +store+ to a base URL string.
+      #
+      # @param store [String, nil] raw store value (domain, URL, etc.)
+      # @return [String] canonical HTTPS base URL with no trailing slash
+      # @raise [ConfigurationError] if store is blank or contains a non-root path
+      #
+      # @example
+      #   StoreUrl.resolve('example.myshopify.com')           # => "https://example.myshopify.com"
+      #   StoreUrl.resolve('https://example.myshopify.com/')  # => "https://example.myshopify.com"
+      #   StoreUrl.resolve('http://example.myshopify.com')    # => "https://example.myshopify.com"
+      def self.resolve(store)
+        raise ConfigurationError, 'store must not be blank' if store.nil? || store.strip.empty?
+
+        uri = parse_uri(store.strip)
+        validate_path!(uri, store.strip)
+        normalise(uri)
+      rescue URI::InvalidURIError => e
+        raise ConfigurationError, "invalid store URL: #{e.message}"
+      end
+
+      # @param raw [String] stripped store string
+      # @return [URI::Generic]
+      def self.parse_uri(raw)
+        raw = "https://#{raw}" unless raw.match?(%r{\Ahttps?://}i)
+        URI.parse(raw)
+      end
+      private_class_method :parse_uri
+
+      # @param uri [URI::Generic]
+      # @param original [String] original stripped store input (for error messages)
+      # @raise [ConfigurationError] if the URI contains a non-root path
+      def self.validate_path!(uri, original)
+        path = uri.path.to_s.delete_suffix('/')
+        return if path.empty?
+
+        raise ConfigurationError, "store must be a bare domain, got path: #{original}"
+      end
+      private_class_method :validate_path!
+
+      # @param uri [URI::Generic]
+      # @return [String] canonical HTTPS base URL
+      def self.normalise(uri)
+        uri.scheme   = 'https'
+        uri.path     = ''
+        uri.query    = nil
+        uri.fragment = nil
+        uri.to_s
+      end
+      private_class_method :normalise
+    end
+  end
+end

data/lib/showroom/core/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Showroom
+  # Internal gem infrastructure (configuration, connection, errors, versioning).
+  module Core
+    # Current gem version.
+    VERSION = '0.1.0'
+  end
+end

data/lib/showroom/http/middleware/raise_error.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module Showroom
+  # Faraday HTTP layer (adapters, middleware).
+  module Http
+    # Faraday middleware classes.
+    module Middleware
+      # Faraday middleware that maps HTTP error statuses and parsing failures
+      # to Showroom error classes.
+      #
+      # @example Registration
+      #   conn.use Showroom::Http::Middleware::RaiseError
+      class RaiseError < Faraday::Middleware
+        # Maps specific HTTP status codes to Showroom error classes.
+        STATUS_MAP = {
+          400 => Showroom::BadRequest,
+          404 => Showroom::NotFound,
+          422 => Showroom::UnprocessableEntity,
+          429 => Showroom::TooManyRequests
+        }.freeze
+
+        # Executes the middleware, rescuing network-level Faraday errors.
+        #
+        # @param env [Faraday::Env]
+        # @raise [ConnectionError] on connection or timeout failure
+        # @raise [InvalidResponse] on JSON parsing failure
+        def call(env)
+          @app.call(env).on_complete { |response_env| on_complete(response_env) }
+        rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+          raise ConnectionError, e.message
+        rescue Faraday::ParsingError
+          raise InvalidResponse,
+                'Response was not JSON — store may be password-protected or blocking requests'
+        end
+
+        private
+
+        # Inspects the completed response and raises the appropriate error.
+        #
+        # @param env [Faraday::Env]
+        # @raise [InvalidResponse] when a 200 response has a non-JSON content-type
+        # @raise [ResponseError] (or subclass) for 4xx/5xx responses
+        def on_complete(env)
+          check_html_response!(env) if env.status == 200
+          raise_for_status!(env) if env.status >= 400
+        end
+
+        # @param env [Faraday::Env]
+        # @raise [InvalidResponse] if Content-Type indicates HTML
+        def check_html_response!(env)
+          content_type = env.response_headers['content-type'].to_s
+          return unless content_type.include?('text/html')
+
+          raise InvalidResponse,
+                'Response was not JSON — store may be password-protected or blocking requests'
+        end
+
+        # @param env [Faraday::Env]
+        # @raise [ResponseError] (or subclass) matching the status code
+        def raise_for_status!(env)
+          klass = error_class(env.status)
+          raise klass.new(nil, status: env.status, body: env.body, headers: env.response_headers)
+        end
+
+        # @param status [Integer]
+        # @return [Class] the most specific matching Showroom error class
+        def error_class(status)
+          STATUS_MAP.fetch(status) do
+            if status >= 500
+              ServerError
+            else
+              ClientError
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/showroom/models/collection.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Showroom
+  # Represents a Shopify collection with class-level query methods
+  # that delegate to {Showroom.client} and an instance-level products fetcher.
+  #
+  # @example Fetching collections
+  #   collections = Showroom::Collection.where
+  #   collection  = Showroom::Collection.find('lorem-helmets')
+  #
+  # @example Fetching products in a collection
+  #   collection.products(limit: 10)
+  class Collection < Resource
+    main_attrs :id, :title, :handle, :products_count
+
+    class << self
+      include Core::Countable
+
+      def index_path = '/collections.json'
+      def index_key  = 'collections'
+      private :index_path, :index_key
+
+      # Fetches collections matching the given query parameters.
+      #
+      # @param params [Hash] Shopify query parameters
+      # @return [Array<Collection>]
+      def where(limit: Showroom.per_page, **params)
+        Showroom.client.get('/collections.json', params.merge(limit: limit))
+                .fetch('collections', [])
+                .map { |h| 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 find(handle)
+        Showroom.client.get("/collections/#{handle}.json")
+                .fetch('collection') { raise Showroom::NotFound, handle }
+                .then { |h| new(h) }
+      end
+    end
+
+    # Returns the number of products in this collection as reported by the API.
+    #
+    # @return [Integer, nil]
+    def products_count
+      @attrs['products_count']
+    end
+
+    # Fetches a single page of products belonging to this collection.
+    #
+    # Returns at most one page of results. Use +limit: 250+ to maximise the
+    # number of products returned in a single request. For collections with
+    # more products than the page size, pass +page:+ explicitly to retrieve
+    # subsequent pages.
+    #
+    # @param params [Hash] Shopify query parameters (e.g. +limit:+, +page:+)
+    # @return [Array<Product>]
+    def products(**params)
+      Showroom.client.get("/collections/#{handle}/products.json", params)
+              .fetch('products', [])
+              .map { |h| Product.new(h) }
+    end
+  end
+end

data/lib/showroom/models/product.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Showroom
+  # Represents a Shopify product with associations, convenience methods,
+  # and class-level query methods that delegate to {Showroom.client}.
+  #
+  # @example Fetching products
+  #   products = Showroom::Product.where(product_type: 'Road Bike')
+  #   product  = Showroom::Product.find('lorem-road-bike')
+  class Product < Resource
+    main_attrs :id, :title, :handle, :vendor, :product_type, :price, :price_range
+
+    has_many :variants, ProductVariant
+    has_many :images,   ProductImage
+    has_many :options,  ProductOption
+
+    class << self
+      include Core::Countable
+
+      def index_path = '/products.json'
+      def index_key  = 'products'
+      private :index_path, :index_key
+
+      # Fetches products matching the given query parameters.
+      #
+      # @param params [Hash] Shopify query parameters (e.g. product_type:, vendor:)
+      # @return [Array<Product>]
+      def where(limit: Showroom.per_page, **params)
+        Showroom.client.get('/products.json', params.merge(limit: limit))
+                .fetch('products', [])
+                .map { |h| 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 find(handle)
+        Showroom.client.get("/products/#{handle}.json")
+                .fetch('product') { raise Showroom::NotFound, handle }
+                .then { |h| new(h) }
+      end
+
+      # Returns an Enumerator that iterates over products across multiple pages.
+      #
+      # You must pass either +max_pages:+ (an explicit ceiling) or set
+      # +force_all_without_limit: true+ to acknowledge that the number of
+      # requests is unbounded. The latter emits a warning.
+      #
+      # @param max_pages [Integer, nil] maximum number of pages to fetch
+      # @param force_all_without_limit [Boolean] when true, fetch all pages
+      #   up to +pagination_depth+ without a hard cap (emits a warning)
+      # @param params [Hash] additional query parameters
+      # @return [Enumerator<Product>]
+      # @raise [ArgumentError] when neither +max_pages:+ nor
+      #   +force_all_without_limit: true+ is given
+      def all(max_pages: nil, force_all_without_limit: false, **params)
+        Enumerator.new do |yielder|
+          each_page(max_pages: max_pages, force_all_without_limit: force_all_without_limit,
+                    **params) do |page_products, _page|
+            page_products.each { |p| yielder << p }
+          end
+        end
+      end
+
+      # Iterates through pages of products, yielding each page.
+      #
+      # You must pass either +max_pages:+ or +force_all_without_limit: true+.
+      # Without an explicit ceiling, unbounded pagination can issue dozens of
+      # HTTP requests silently. When +force_all_without_limit: true+ is given,
+      # a warning is emitted and iteration proceeds up to +pagination_depth+.
+      #
+      # @param max_pages [Integer, nil] maximum number of pages to fetch
+      # @param force_all_without_limit [Boolean] bypass the requirement at your
+      #   own risk; emits a +Kernel.warn+ and uses +pagination_depth+ as the cap
+      # @param limit [Integer] results per page (defaults to +Showroom.per_page+)
+      # @param params [Hash] additional query parameters
+      # @yield [products, page] the products for this page and the 1-based page number
+      # @yieldparam products [Array<Product>]
+      # @yieldparam page [Integer]
+      # @return [void]
+      # @raise [ArgumentError] when neither +max_pages:+ nor
+      #   +force_all_without_limit: true+ is given
+      def each_page(max_pages: nil, force_all_without_limit: false, limit: Showroom.per_page, **params, &blk)
+        validate_pagination_args!(max_pages, force_all_without_limit)
+        effective_depth = max_pages || Showroom.client.pagination_depth
+        Showroom.client.paginate('/products.json', 'products', params.merge(limit: limit),
+                                 max_pages: effective_depth) do |items, page|
+          blk.call(items.map { |h| new(h) }, page)
+        end
+      end
+
+      private
+
+      def validate_pagination_args!(max_pages, force_all_without_limit)
+        if max_pages.nil? && !force_all_without_limit
+          raise ArgumentError,
+                'Product.each_page requires max_pages: N or force_all_without_limit: true. ' \
+                'Unbounded pagination can issue many HTTP requests. ' \
+                'Pass max_pages: to set an explicit ceiling.'
+        end
+        return unless force_all_without_limit && max_pages.nil?
+
+        warn '[Showroom] force_all_without_limit: true — pagination is unbounded and may issue ' \
+             "up to #{Showroom.client.pagination_depth} HTTP requests."
+      end
+    end
+
+    # Returns the lowest variant price as a String.
+    #
+    # @return [String, nil]
+    def price
+      variants.min_by { |v| v['price'].to_f }&.then { |v| v['price'] }
+    end
+
+    # Returns a price range string ("min–max") or just the price if all variants
+    # share the same price.
+    #
+    # @return [String, nil]
+    def price_range
+      prices = variants.map { |v| v['price'] }.uniq
+      return nil if prices.empty?
+
+      prices.length == 1 ? prices.first : "#{prices.min} - #{prices.max}"
+    end
+
+    # Returns true when at least one variant is available for purchase.
+    #
+    # @return [Boolean]
+    def available?
+      variants.any?(&:available?)
+    end
+
+    # Returns the first image, or nil if there are no images.
+    #
+    # @return [ProductImage, nil]
+    def featured_image
+      images.first
+    end
+  end
+end

data/lib/showroom/models/product_image.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Showroom
+  # Represents a Shopify product image.
+  #
+  # @example
+  #   image = ProductImage.new('id' => 1, 'src' => 'https://example.com/img.jpg')
+  #   image.src # => "https://example.com/img.jpg"
+  class ProductImage < Resource
+    main_attrs :id, :src, :position
+  end
+end

data/lib/showroom/models/product_option.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Showroom
+  # Represents a Shopify product option (e.g. Size, Color).
+  #
+  # @example
+  #   opt = ProductOption.new('name' => 'Size', 'position' => 1, 'values' => ['S', 'M'])
+  #   opt.name   # => "Size"
+  #   opt.values # => ["S", "M"]
+  class ProductOption < Resource
+    main_attrs :name, :position
+  end
+end

data/lib/showroom/models/product_variant.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Showroom
+  # Represents a Shopify product variant.
+  #
+  # @example
+  #   variant = ProductVariant.new('title' => 'S / Red', 'price' => '899.00', 'available' => true)
+  #   variant.available? # => true
+  #   variant.on_sale?   # => false
+  class ProductVariant < Resource
+    main_attrs :id, :title, :price, :sku
+
+    # Returns true when the variant is available for purchase.
+    #
+    # @return [Boolean]
+    def available?
+      @attrs['available'] == true
+    end
+
+    # Returns true when +compare_at_price+ is present and greater than +price+.
+    #
+    # @return [Boolean]
+    def on_sale?
+      cap = @attrs['compare_at_price']
+      return false if cap.nil? || cap.to_s.empty?
+
+      cap.to_f > @attrs['price'].to_f
+    end
+
+    # Returns the selected options for this variant as an Array of values.
+    #
+    # Collects option1, option2, option3 in order, omitting nil values.
+    #
+    # @return [Array<String>]
+    def options
+      [@attrs['option1'], @attrs['option2'], @attrs['option3']].compact
+    end
+  end
+end

data/lib/showroom/models/resource.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Showroom
+  # Base class for all Showroom model objects.
+  #
+  # Wraps a plain Hash, providing dot-notation attribute access, association
+  # DSL macros ({.has_many} / {.has_one}), deep serialization via {#to_h},
+  # and a configurable {#inspect} output via {.main_attrs}.
+  #
+  # @example Basic usage
+  #   resource = Resource.new('id' => 1, 'title' => 'Foo')
+  #   resource.id     # => 1
+  #   resource.title  # => "Foo"
+  class Resource
+    # @return [Hash] the normalized attribute hash
+    attr_reader :attrs
+
+    # Initializes a Resource from a Hash, normalizing all keys to strings.
+    #
+    # @param hash [Hash] attribute data
+    def initialize(hash = {})
+      @attrs = hash.transform_keys(&:to_s)
+    end
+
+    class << self
+      # Declares which attribute keys are included in {#inspect} output.
+      #
+      # @param keys [Array<Symbol>] attribute names to display in inspect
+      # @return [void]
+      def main_attrs(*keys)
+        @main_attrs = keys.map(&:to_s)
+      end
+
+      # Returns the list of keys configured via {.main_attrs}.
+      #
+      # @return [Array<String>]
+      def main_attr_keys
+        @main_attrs || []
+      end
+
+      # Defines a reader that wraps the array at +attrs[name]+ as instances
+      # of +klass+.
+      #
+      # @param name [Symbol] attribute name (plural)
+      # @param klass [Class] model class to wrap each element in
+      # @return [void]
+      def has_many(name, klass) # rubocop:disable Naming/PredicatePrefix
+        define_method(name) do
+          @attrs[name.to_s] = Array(@attrs[name.to_s]).map do |item|
+            item.is_a?(klass) ? item : klass.new(item)
+          end
+          @attrs[name.to_s]
+        end
+      end
+
+      # Defines a reader that wraps the hash at +attrs[name]+ as an instance
+      # of +klass+, or returns +nil+ when absent.
+      #
+      # @param name [Symbol] attribute name (singular)
+      # @param klass [Class] model class to wrap the value in
+      # @return [void]
+      def has_one(name, klass) # rubocop:disable Naming/PredicatePrefix
+        define_method(name) do
+          value = @attrs[name.to_s]
+          return nil if value.nil?
+
+          value.is_a?(klass) ? value : klass.new(value)
+        end
+      end
+    end
+
+    # Raw access to an attribute by key.
+    #
+    # @param key [String, Symbol] attribute name
+    # @return [Object, nil]
+    def [](key)
+      @attrs[key.to_s]
+    end
+
+    # Deep-converts the resource (and any nested resources) back to a plain Hash.
+    #
+    # @return [Hash]
+    def to_h
+      @attrs.transform_values { |v| deep_unwrap(v) }
+    end
+
+    # Returns a developer-friendly string showing {.main_attrs} values.
+    #
+    # @return [String]
+    def inspect
+      keys = self.class.main_attr_keys
+      pairs = keys.filter_map do |k|
+        value = @attrs[k]
+        "#{k}: #{value.inspect}" if @attrs.key?(k)
+      end
+      "#<#{self.class.name} #{pairs.join(', ')}>"
+    end
+
+    # Compares two resources by their underlying attribute hashes.
+    #
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(self.class) && other.attrs == @attrs
+    end
+
+    # Delegates attribute lookups to @attrs, and caches the method on first call.
+    #
+    # @param name [Symbol] method name
+    # @param args [Array] method arguments (none expected for attr readers)
+    # @return [Object, nil]
+    def method_missing(name, *args, &)
+      key = name.to_s
+      if @attrs.key?(key)
+        self.class.define_method(name) { @attrs[key] }
+        @attrs[key]
+      else
+        super
+      end
+    end
+
+    # @param name [Symbol]
+    # @param include_private [Boolean]
+    # @return [Boolean]
+    def respond_to_missing?(name, include_private = false)
+      @attrs.key?(name.to_s) || super
+    end
+
+    private
+
+    # Recursively converts Resource instances and arrays back to plain values.
+    #
+    # @param value [Object]
+    # @return [Object]
+    def deep_unwrap(value)
+      case value
+      when Resource then value.to_h
+      when Array    then value.map { |v| deep_unwrap(v) }
+      else               value
+      end
+    end
+  end
+end

data/lib/showroom/models/search/article_suggestion.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Showroom
+  module Search
+    # A lean article shape returned by the Shopify search suggest endpoint.
+    #
+    # @example
+    #   suggestion = Showroom::Search::ArticleSuggestion.new('title' => 'How to Choose a Road Bike')
+    #   suggestion.title  # => "How to Choose a Road Bike"
+    class ArticleSuggestion < Suggestion
+      main_attrs :id, :title, :handle
+    end
+  end
+end

data/lib/showroom/models/search/collection_suggestion.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Showroom
+  module Search
+    # A lean collection shape returned by the Shopify search suggest endpoint.
+    #
+    # @example
+    #   suggestion = Showroom::Search::CollectionSuggestion.new('title' => 'Lorem Helmets', 'handle' => 'lorem-helmets')
+    #   suggestion.title  # => "Lorem Helmets"
+    class CollectionSuggestion < Suggestion
+      main_attrs :id, :title, :handle
+
+      # @return [Class] the full model class for this suggestion type
+      def self.complete_model_class
+        Collection
+      end
+    end
+  end
+end

data/lib/showroom/models/search/page_suggestion.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Showroom
+  module Search
+    # A lean page shape returned by the Shopify search suggest endpoint.
+    #
+    # @example
+    #   suggestion = Showroom::Search::PageSuggestion.new(
+    #     'title' => 'About Lorem Bikes', 'handle' => 'about-lorem-bikes'
+    #   )
+    #   suggestion.title  # => "About Lorem Bikes"
+    class PageSuggestion < Suggestion
+      main_attrs :id, :title, :handle
+    end
+  end
+end

data/lib/showroom/models/search/product_suggestion.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Showroom
+  module Search
+    # A lean product shape returned by the Shopify search suggest endpoint.
+    #
+    # @example
+    #   suggestion = Showroom::Search::ProductSuggestion.new('title' => 'Lorem Road Bike', 'price' => '899.00')
+    #   suggestion.title  # => "Lorem Road Bike"
+    #   suggestion.price  # => "899.00"
+    class ProductSuggestion < Suggestion
+      main_attrs :id, :title, :handle, :price
+
+      # @return [Class] the full model class for this suggestion type
+      def self.complete_model_class
+        Product
+      end
+    end
+  end
+end

data/lib/showroom/models/search/query_suggestion.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Showroom
+  module Search
+    # A query suggestion returned by the Shopify search suggest endpoint.
+    #
+    # @example
+    #   suggestion = Showroom::Search::QuerySuggestion.new('text' => 'lorem road bike')
+    #   suggestion.text  # => "lorem road bike"
+    class QuerySuggestion < Suggestion
+      main_attrs :text
+    end
+  end
+end