aboutyou-sdk 0.0.9 → 0.0.10

data/lib/aboutyou-sdk/Criteria/ProductSearchCriteria.rb

@@ -1,435 +1,468 @@
 module AboutYou
   module SDK
     module Criteria
+      ###
+      # This class is used as the criteria for a product search
+      # Its instance is meant to be passed to the fetchProducrSearch method
+      # To add a specific criteria simply call the method on the instance
+      #
+      # author:: Collins GmbH & Co KG
+      ###
       class ProductSearchCriteria
-          SORT_TYPE_RELEVANCE   = 'relevance';
-          SORT_TYPE_UPDATED     = 'updated_date';
-          SORT_TYPE_CREATED     = 'created_date';
-          SORT_TYPE_MOST_VIEWED = 'most_viewed';
-          SORT_TYPE_PRICE       = 'price';
-
-          SORT_ASC  = 'asc';
-          SORT_DESC = 'desc';
-
-          FACETS_ALL = '_all';
-          FACETS_UNLIMITED = -1;
-
-          FILTER_SALE          = 'sale';
-          FILTER_CATEGORY_IDS  = 'categories';
-          FILTER_PRICE         = 'prices';
-          FILTER_SEARCHWORD    = 'searchword';
-          FILTER_ATTRIBUTES    = 'facets';
-
-          attr_accessor :filter
-          attr_accessor :result
-          attr_accessor :sessionId
-
-           ###
-           # @param string $sessionId
-           ###
-          def initialize(sessionId)
-
-              self.filter    = Hash.new
-              self.sessionId = sessionId
-              self.result    = Hash.new
+        # api-call-name for sorting after relevance
+        SORT_TYPE_RELEVANCE   = 'relevance'
+        # api-call-name for sorting after updated_date
+        SORT_TYPE_UPDATED     = 'updated_date'
+        # api-call-name for sorting after created_date
+        SORT_TYPE_CREATED     = 'created_date'
+        # api-call-name for sorting after most_viewed
+        SORT_TYPE_MOST_VIEWED = 'most_viewed'
+        # api-call-name for sorting after price
+        SORT_TYPE_PRICE       = 'price'
+
+        # api-call-name for sorting ascending
+        SORT_ASC  = 'asc'
+        # api-call-name for sorting descending
+        SORT_DESC = 'desc'
+
+        # api-call name for requiring all facets
+        FACETS_ALL = '_all'
+
+        # api-call-value for requiring unlimited facets
+        FACETS_UNLIMITED = -1
+
+        # api-call-name for filtering the sale
+        FILTER_SALE          = 'sale'
+        # api-call-name for filtering the categories
+        FILTER_CATEGORY_IDS  = 'categories'
+        # api-call-name for filtering the prices
+        FILTER_PRICE         = 'prices'
+        # api-call-name for filtering the searchword
+        FILTER_SEARCHWORD    = 'searchword'
+        # api-call-name for filtering the facets
+        FILTER_ATTRIBUTES    = 'facets'
+
+        # the filter applied to the api-call
+        attr_accessor :filter
+        # a specification of the result which should be fetched from api
+        attr_accessor :result
+        # the session id of a user
+        attr_accessor :sessionId
+
+        ###
+        # Constructor for AboutYou::SDK::Criteria::ProductSearchCriteria
+        #
+        # * *Args*    :
+        #   - +sessionId+ -> the session is of an user
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def initialize(sessionId)
+          self.filter    = {}
+          self.sessionId = sessionId
+          self.result    = {}
+        end
+
+        ###
+        # adds the filter passed to the api the given filter value
+        #
+        # * *Args*    :
+        #   - +key+ -> the name of the filter which should be applied
+        #   - +value+ -> the value of the filter which should be applied
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def filterBy(key, value)
+          filter[key] = value
+          return self
+        end
+
+        ###
+        # gets the filter value of a given filter key
+        #
+        # * *Args*    :
+        #   - +key+ -> the name of the filter which value should be returned
+        #
+        # * *Returns* :
+        #   - either a value of a filter or nil if filter key not set
+        ###
+        def filter(key)
+          @filter[key] if @filter[key]
+        end
+
+        ###
+        # sets a filter for filtering by sale
+        #
+        # * *Args*    :
+        #   - +sale+ -> determines whether to filter by sale or not [optional]
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def filterBySale(sale = true)
+          unless sale.is_a?(TrueClass) || sale.is_a?(FalseClass) 
+            sale = nil
           end
 
-
-           ###
-           # @param string $key
-           # @param string $value
-           #
-           # @return ProductSearchCriteria
-           ###
-          def filterBy(key, value)
-
-              self.filter[key] = value
-              return self
-          end
-
-           ###
-           # @param string $key
-           #
-           # @return null|mixed
-           ###
-          def getFilter(key)
-              if(self.filter[key])
-                return self.filter[key]
-              end
-
-              return nil
-          end
-
-           ###
-           # @param boolean|null $sale
-           #    true => only sale products
-           #    false => no sale products
-           #    null => both (default)
-           #
-           # @return ProductSearchCriteria
-           ###
-          def filterBySale(sale = true)
-
-            if !(sale.is_a?(TrueClass) || sale.is_a?(FalseClass)) 
-                  sale = nil;
-              end
-
-              return self.filterBy(FILTER_SALE, sale);
-          end
-
-           ###
-           # @return boolean|null
-           ###
-          def saleFilter()
-
-              return self.filter(FILTER_SALE);
-          end
-
-           ###
-           # @param string $searchword
-           #
-           # @return ProductSearchCriteria
-           ###
-          def filterBySearchword(searchword)
-
-              return self.filterBy(FILTER_SEARCHWORD, searchword);
-          end
-
-           ###
-           # @return string|null
-           ###
-          def searchwordFilter()
-
-              return self.filter(FILTER_SEARCHWORD);
+          self.filterBy(FILTER_SALE, sale)
+        end
+
+        ###
+        # sets a filter for filtering by a searchword
+        #
+        # * *Args*    :
+        #   - +searchword+ -> the searchword which should be used for filtering
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def filterBySearchword(searchword)
+          self.filterBy(FILTER_SEARCHWORD, searchword)
+        end
+
+        ###
+        # sets a filter for filtering by category ids
+        #
+        # * *Args*    :
+        #   - +categoryIds+ -> the category ids used for filtering
+        #   - +append+ -> determines whether to append the category ids to an already set value or not [optional]
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def filterByCategoryIds(categoryIds, append = false)
+          if append && self.filter[FILTER_CATEGORY_IDS]
+            categoryIds = self.filter[FILTER_CATEGORY_IDS] + categoryIds
           end
-
-           ###
-           # @param integer[] $categoryIds  array of integer
-           # @param boolean $append         if true the category ids will added to current filter
-           #
-           # @return ProductSearchCriteria
-           ###
-          def filterByCategoryIds(categoryIds, append = false)
-
-            if (append && self.filter[FILTER_CATEGORY_IDS])
-              categoryIds = self.filter[FILTER_CATEGORY_IDS] + categoryIds
+          categoryIds = categoryIds.uniq
+
+          self.filterBy(FILTER_CATEGORY_IDS, categoryIds);
+        end
+
+
+        ###
+        # sets a filter for filtering by category ids
+        #
+        # * *Args*    :
+        #   - +attributes+ -> Array of Hashes containing the relation Group_Id => Facet_Id
+        #   - +append+ -> determines whether to append the category ids to an already set value or not [optional]
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def filterByFacetIds(attributes, append = false)
+          if append && self.filter[FILTER_ATTRIBUTES]
+            merged = self.filter[FILTER_ATTRIBUTES]
+            attributes.each do |groupId, facetIds|
+              if merged.key?(groupId)
+                merged[groupId] = (merged[groupId] + facetIds).uniq
+              else
+                merged[groupId] = facetIds
+              end 
             end
-              categoryIds = categoryIds.uniq
-
-              return self.filterBy(FILTER_CATEGORY_IDS, categoryIds);
+            attributes = merged
           end
-
-           ###
-           # @return integer[]|null
-           ###
-          def categoryFilter()
-
-              return self.filter(FILTER_CATEGORY_IDS)
-          end
-
-           ###
-           # @param array $attributes  array of array with group id and attribute ids
-           #   for example [0 => [264]]: search for products with the brand "TOM TAILER"
-           # @param boolean $append, if true the category ids will added to current filter
-           #
-           # @return ProductSearchFilter
-           ###
-          def filterByFacetIds(attributes, append = false)
           
-            if (append && self.filter[FILTER_ATTRIBUTES])
-                  merged = self.filter[FILTER_ATTRIBUTES];
-                  attributes.each do |groupId, facetIds|
-                    if (merged.key?(groupId)) 
-                      merged[groupId] = (merged[groupId] + facetIds).uniq;
-                    else
-                      merged[groupId] = facetIds;
-                    end 
-                  end
-                  
-                  attributes = merged;
-            end
-              return self.filterBy(FILTER_ATTRIBUTES, attributes);
-          end
-
-           ###
-           # @return array|null
-           # @see filterByFacetIds()
-           ###
-          def facetFilter()
-
-              return self.filter(FILTER_ATTRIBUTES);
-          end
-
-           ###
-           # @param FacetGroup $facetGroup
-           # @param boolean $append, if true the category ids will added to current filter
-           #
-           # @return ProductSearchCriteria
-           ###
-          def filterByFacetGroup(facetGroup, append = false)
-
-              return self.filterByFacetIds(facetGroup.ids(), append);
-          end
-
-           ###
-           # @param FacetGroupSet $facetGroupSet
-           # @param boolean $append, if true the category ids will added to current filter
-           #
-           # @return ProductSearchCriteria
-           ###
-          def filterByFacetGroupSet(facetGroupSet, append = false)
-
-              return self.filterByFacetIds(facetGroupSet.ids(), append);
-          end
-
-           ###
-           # @param integer $from  must be 1 or greater
-           # @param integer $to    must be 1 or greater
-           #
-           # @return ProductSearchCriteria
-           ###
-          def filterByPriceRange(from = 0, to = 0)
-
-            from = Integer(from)
-              to = Integer(to)
-
-              price = Hash.new;
-              if (from > 0) 
-                  price["from"] = from
-              end
-              if (to > 0) 
-                  price["to"] = to
-              end
-
-              return self.filterBy(FILTER_PRICE, price);
-          end
-
-           ###
-           # Returns an associative array with could contains "to" and/or "from", eg.
-           # ["from" => 100, "to" => 10000] or ["to" => 20000]
-           #
-           # @return array|null
-           ###
-          def priceRangeFilter()
-
-              return self.filter(FILTER_PRICE);
-          end
-
-           ###
-           # @param string $type
-           # @param string $direction
-           #
-           # @return $this
-           ###
-          def sortBy(type, direction = SORT_ASC)
-
-              self.result['sort'] = Hash[
-                  'by'        => type,
-                  'direction' => direction,
-              ]
-
-              return self;
-          end
-
-           ###
-           # @param integer $limit
-           # @param integer $offset
-           #
-           # @return $this
-           ##
-          def setLimit(limit, offset = 0)
-
-              limit = [[limit, 200].min, 0].max
-              self.result['limit'] = limit
-
-              offset = [offset, 0].max;
-              self.result['offset'] = offset
-
-              return self;
-          end
-
-           ###
-           # @param bool $enable
-           #
-           # @return $this
-           ###
-          def selectSales(enable = true)
-
-              if (enable) 
-                  self.result['sale'] = true
-              else 
-                  self.result['sale'] = nil
-              end
-
-              return self;
-          end
-
-           ###
-           # @param bool $enable
-           #
-           # @return $this
-           ###
-          def selectPriceRanges(enable = true)
-
-              if (enable) 
-                  self.result['price'] = true
-              else 
-                  self.result['price'] = nil
-              end
-
-              return self;
-          end
-
-           ###
-           # @param integer|string $groupId
-           # @param integer $limit
-           #
-           # @return $this
-           #
-           # @throws \InvalidArgumentException
-           ###
-          def selectFacetsByGroupId(groupId, limit)
-
-              self.checkFacetLimit(limit);
-              if (!(groupId.is_a? Fixnum) && (Integer(groupId)).nil?)
-                  raise InvalidArgumentException();
-              end
-
-              if (!self.result['facets']) 
-                  self.result['facets'] = Hash.new
-              end
-
-              if !(self.result['facets'][groupId]) 
-                  self.result['facets'][String(groupId)] = Hash['limit' => limit];
-              end
-              return self;
+          self.filterBy(FILTER_ATTRIBUTES, attributes)
+        end
+
+
+        ###
+        # sets a filter for filtering by Facet-Group
+        #
+        # * *Args*    :
+        #   - +facetGroup+ -> Instance of AboutYou::SDK::Model::FacetGroup
+        #   - +append+ -> determines whether to append the category ids to an already set value or not [optional]
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def filterByFacetGroup(facetGroup, append = false)
+          self.filterByFacetIds(facetGroup.ids, append)
+        end
+
+        ###
+        # sets a filter for filtering by Facet-Groupset
+        #
+        # * *Args*    :
+        #   - +facetGroupSet+ -> Instance of AboutYou::SDK::Model::FacetGroupSet
+        #   - +append+ -> determines whether to append the category ids to an already set value or not [optional]
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def filterByFacetGroupSet(facetGroupSet, append = false)
+          self.filterByFacetIds(facetGroupSet.ids, append)
+        end
+
+        ###
+        # sets a filter for filtering by Price range
+        #
+        # * *Args*    :
+        #   - +from+ -> states the starting value of the price filter
+        #   - +to+ -> states the end value of the price filter
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def filterByPriceRange(from = 0, to = 0)
+          from = Integer(from)
+          to = Integer(to)
+          price = {}
+          
+          price["from"] = from if from > 0
+          price["to"] = to if to > 0
+
+          self.filterBy(FILTER_PRICE, price)
+        end
+
+        ###
+        # sets a sorting-filter and direction
+        #
+        # * *Args*    :
+        #   - +type+ -> states the type of the sorting
+        #   - +direction+ -> the direction of the sorting [optional]
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def sortBy(type, direction = SORT_ASC)
+          self.result['sort'] = {
+            'by'        => type,
+            'direction' => direction,
+          }
+          self
+        end
+
+        ###
+        # sets a limit and offset for the product search
+        #
+        # * *Args*    :
+        #   - +limit+ -> limits the amount of results received from the api
+        #   - +offset+ -> sets an offset to skip results [optional]
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def setLimit(limit, offset = 0)
+          limit = [[limit, 200].min, 0].max
+          self.result['limit'] = limit
+
+          offset = [offset, 0].max
+          self.result['offset'] = offset
+          self
+        end
+
+        ###
+        # this method determines whether you receive only sales products or not
+        #
+        # * *Args*    :
+        #   - +enable+ -> if true api will return only sales products [optional]
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def selectSales(enable = true)
+          if enable
+            self.result['sale'] = true
+          else 
+            self.result['sale'] = nil
           end
-
-           ###
-           # @param FacetGetGroupInterface $group
-           # @param integer $limit
-           #
-           # @return $this
-           ###
-          def selectFacetsByFacetGroup(group, limit)
-
-              return self.selectFacetsByGroupId(group.getGroupId(), limit);
+          
+          self
+        end
+
+        ###
+        # this method determines whether you receive price ranges or not
+        #
+        # * *Args*    :
+        #   - +enable+ -> if true api will return price ranges [optional]
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def selectPriceRanges(enable = true)
+          if enable 
+            self.result['price'] = true
+          else 
+            self.result['price'] = nil
           end
 
-           ###
-           # @param integer $limit
-           #
-           # @return $this
-           ###
-          def selectAllFacets(limit)
-
-              self.checkFacetLimit(limit);
-              self.result['facets'] = Hash[self::FACETS_ALL => Hash['limit' => limit]];
-
-              return self;
+          self
+        end
+
+        ###
+        # this method adds a field to the api-request which enables you to 
+        # receive Facets by a given group id
+        #
+        # * *Args*    :
+        #   - +groupId+ -> group id which facets you want to receive
+        #   - +limit+ -> limits the received facets
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def selectFacetsByGroupId(groupId, limit)
+          self.checkFacetLimit(limit)
+          unless groupId.is_a?(Fixnum) && Integer(groupId)
+            raise "InvalidArgumentException! Group id must be an integer or a
+            string containing digits"
           end
-
-          def checkFacetLimit(limit)
-
-              if !((limit.is_a? Fixnum) || (limit.is_a? Integer)) 
-                  raise  InvalidArgumentException('limit must be an integer');
-              end
-              if (limit < -1) 
-                  raise InvalidArgumentException('limit must be positive or -1 for unlimited facets');
-              end
+          unless self.result['facets']
+            self.result['facets'] = {}
           end
-
-           ###
-           # @param bool $enable
-           #
-           # @return $this
-           ###
-          def selectCategories(enable = true)
-
-              if (enable) 
-                  self.result['categories'] = true;
-              else 
-                  self.result['categories'] = nil;
-              end
-
-              return self;
+          unless self.result['facets'][groupId]
+            self.result['facets'][String(groupId)] = {'limit' => limit}
           end
-
-           ###
-           # @param integer|Product[] $ids
-           #
-           # @return $this
-           ###
-          def boostProducts(ids)
-
-              ids = ids.map{
-                |val|
-                if val.instance_of? Product
-                  return val.getId()
-                end 
-                return Integer(val)
-                }
-              ids = ids.uniq;
-              self.result['boosts'] = ids;
-
-              return self;
+          
+          self
+        end
+
+        ###
+        # this method will make the api return all facets
+        #
+        # * *Args*    :
+        #   - +limit+ -> limits the received facets
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def selectAllFacets(limit)
+          self.checkFacetLimit(limit)
+          self.result['facets'] = {self::FACETS_ALL => {'limit' => limit}}
+
+          self
+        end
+
+        ###
+        # this method checks whether a given facet limit is valid or not
+        #
+        # * *Args*    :
+        #   - +limit+ -> limit which should be checked
+        #
+        # * *Returns* :
+        #   - nil if there is no error
+        ###
+        def checkFacetLimit(limit)
+          unless limit.is_a?(Fixnum) || limit.is_a?(Integer) 
+            raise 'InvalidArgumentException! limit must be an integer'
           end
-
-           ###
-           # @param string[] $fields
-           #
-           # @return $this
-           ###
-          def selectProductFields(fields)
-
-            self.result['fields'] = AboutYou::SDK::Criteria::ProductFields.filterFields(fields);
-
-              return self;
+          if limit < -1
+            raise 'InvalidArgumentException! limit must be positive or -1 for unlimited facets'
           end
-
-           ###
-           # @param string $sessionId
-           #
-           # @return $this
-           #
-          def setSessionId(sessionId)
-
-              self.sessionId = sessionId;
-
-              return self;
+        end
+
+        ###
+        # this method lets the api return the categories if stated so
+        #
+        # * *Args*    :
+        #   - +enable+ -> determines whether or not the categories should be received from the api [optional]
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def selectCategories(enable = true)
+          if enable
+            self.result['categories'] = true
+          else 
+            self.result['categories'] = nil
           end
-          
-          def requiresCategories()
-
-            productCategories = (self.result.has_key?('fields') && AboutYou::SDK::Criteria::ProductFields.requiresCategories(self.result['fields']))
-            categoryFacets = (self.result.has_key?('categories') && self.result['categories'])
 
-            return (productCategories || categoryFacets)
+          self
+        end
+
+        ###
+        # this method lets the api return products. It will prefer to return
+        # products which are given by +ids+
+        #
+        # * *Args*    :
+        #   - +ids+ -> the products which should be boosted or the ids of them
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def boostProducts(ids)
+          mappedIds = []
+          ids = ids.map{
+            |val|
+            if val.instance_of?(Product)
+              mappedIds.push(val.id)
+            end
+            mappedIds.push(val)
+          }
+          mappedIds = mappedIds.uniq
+          self.result['boosts'] = ids
+
+          self
+        end
+
+        ###
+        # this method lets you select certain
+        # AboutYou::SDK::Criteria::ProductFields which will be returned from api
+        #
+        # * *Args*    :
+        #   - +fields+ -> an Array of constants from AboutYou::SDK::Criteria::ProductFields
+        #
+        # * *Returns* :
+        #   - an instance of AboutYou::SDK::Criteria::ProductSearchCriteria
+        ###
+        def selectProductFields(fields)
+          self.result['fields'] = 
+            AboutYou::SDK::Criteria::ProductFields.filterFields(fields)
+
+          self
+        end
+
+        ###
+        # this method decides whether categories are required to fetch from api
+        #
+        # * *Returns* :
+        #   - a boolean stating whether to fetch categories from api or not
+        ###
+        def requiresCategories
+          (self.result.has_key?('fields') &&
+          AboutYou::SDK::Criteria::ProductFields.
+          requiresCategories(self.result['fields'])) ||
+          (self.result.has_key?('categories') &&
+          self.result['categories'])
+        end
+
+        ###
+        # this method decides whether facets are required to fetch from api
+        #
+        # * *Returns* :
+        #   - a boolean stating whether to fetch facets from api or not
+        ###
+        def requiresFacets
+          (self.result.key?('fields') &&
+          AboutYou::SDK::Criteria::ProductFields.
+          requiresFacets(self.result['fields'])) ||
+          (self.result.key?('facets') &&
+          !self.result['facets'].empty?)
+        end
+
+        ###
+        # this method turns an instance of
+        # AboutYou::SDK::Criteria::productSearchCriteria in an Array which can
+        # be passed directly to the api 
+        #
+        # * *Returns* :
+        #   - an Array containing all the parameters set on the instance
+        ###
+        def toArray
+          params = {'session_id' => self.sessionId}
+
+          if self.result
+            params['result'] = self.result
           end
-
-          def requiresFacets()
-            
-            productFacets = (self.result.key?('fields') && AboutYou::SDK::Criteria::ProductFields.requiresFacets(self.result['fields']))
-            facetFacets = (self.result.key?('facets') && !self.result['facets'].empty?)
-            return (productFacets || facetFacets)
+          unless @filter.empty?
+            params['filter'] = self.filter
           end
 
-           ###
-           # @return array
-           ###
-          def toArray()
-
-            params = Hash['session_id' => self.sessionId]
-
-            if !(self.result.empty?) 
-                params['result'] = self.result;
-            end
-            if (self.filter) 
-                params['filter'] = self.filter;
-            end
-
-            return params;
-          end
+          params
+        end
       end
     end
   end