aboutyou-sdk 0.0.8 → 0.0.9

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    OTM0MmUzNTAxZDAzY2NiMmVhNzg4YjY1MmYzYjBhZmMzNjg3ODFlNw==
+    NjEwNWU3MTUxOGVmMWM4OGU1NmI3N2EzODUxZDQxNDc4MTYwMDg1ZA==
   data.tar.gz: !binary |-
-    ZTg2NzY5NzQ3YWQzM2Q4ZDI5MTRkOGJkOGYyZmFkYTdhMWZkMzU1NQ==
+    ZjJhZTViOGQzOTNmNGQzN2RmNjY2YjE5ZjMyNWJlNWZmZjczNjQ4Yg==
 SHA512:
   metadata.gz: !binary |-
-    ZDM1NTc0ZjFmZmVlYjI0YWY0YTI1MTk2MGYyNTkwMGNiOWZmNDI1NjA0MzUx
-    ZWQzMGNlNjVlMzI0YjY3MTZkYTIyMmI2NjlmOGZiMzVmZjY3ZTk3NmU1YTM5
-    ZTk2NmM1MTM5NmRkOTkzYzk5ZWI4YzhkOGYwNzNmMGEzNzczNGQ=
+    N2IyNDAyNTE1OGY2MjY3YmRkZjQ4ZjY5ZWY0NWY3OTBjNmY5YjRhYzAxYmRl
+    YmI1YWNhOTE1YzllNDAwMGQ1MjIyNTIyMjdhMTJhMmQ5ZWE3Y2IyZThiNzlh
+    ZmZmZDhiZjg0ZWE4MGFiZGJjZThlZjQ1YjlmNzYwZTJmYjYxMzY=
   data.tar.gz: !binary |-
-    ZmE2MTI3OThmMjRlODhhMTNlNGQ1M2ExOTJmYzFhOTNjNjU0YWMzNWZmMDI4
-    OWEyODkyNWIyNzMwZTU2NjA2M2MwZDRmYTA4Y2MxOGNjY2JlYzM1ZjAyNjJl
-    ZWVhYWUyMWQ0ZGMxODIxYmU5ZmM5MmQyMzVkMGQxMGYyZjM5YmI=
+    NjExZDYwM2U1YTdiZWNmY2EyZDdiYmEwYjAwZDJiZjkzOWE1NmRlZDA1Y2Nm
+    NTVlYjRmMzhjMmZmNjBjNDU1ZDQ3MjE0OTBjMzVkOTIzNThjNmEyNThkMmU3
+    NjIwYjk1MDg0NTQ3N2NiNDgzNWFlYzhiM2I0NjFhZTE0MWFiNDI=

data/lib/aboutyou-sdk.rb

@@ -8,7 +8,7 @@ require_rel "aboutyou-sdk"
  # Provides access to the Collins Frontend Platform.
  # All the public methods cover a single API query.
  #
- # @author Collins GmbH & Co KG
+ # author:: Collins GmbH & Co KG
  ###
 class AY
   IMAGE_URL_STAGE   = 'http://mndb.staging.aboutyou.de/mmdb/file'
@@ -26,16 +26,35 @@ class AY
   attr_accessor :sessionId
 
    ###
-   # @param apiEndPoint=>live    = AboutYou::SDK::Constants::API_ENVIRONMENT_LIVE
-   # @param apiEndPoint=>staging = AboutYou::SDK::Constants::API_ENVIRONMENT_STAGE
-   # @param resultFactory if null it will use the DefaultModelFactory with the DefaultFacetManager
-   ###
-  def initialize(appId,appPassword,sessionId = 'SESSION_ID', apiEndPoint = AboutYou::SDK::Constants::API_ENVIRONMENT_LIVE, resultFactory = nil, logger = nil,facetManagerCache = nil)
+   # the Constructor for the AY class
+   #
+   # * *Args*    :
+   #   - +appId+ -> The App-Id of the App
+   #   - +appPassword+ -> The Auth-Token of the App
+   #   - +sessionId+ -> A String containing the sessionId of the User
+   #   - +apiEndPoint+ -> Can be either live or staging
+   #   - +resultFactory+ -> If nil it will use the DefaultModelFactory with the DefaultFacetManager
+   #   - +logger+ -> Logger-Template
+   #   - +facetManagerCache+ -> The prefered Caching-Strategy
+   #   
+   # * *Returns* :
+   #   - Instance of AY
+   ###
+  def initialize(
+      appId,
+      appPassword,
+      sessionId = 'SESSION_ID',
+      apiEndPoint = AboutYou::SDK::Constants::API_ENVIRONMENT_LIVE,
+      resultFactory = nil,
+      logger = nil,
+      facetManagerCache = nil
+  )
     
     self.sessionId   = sessionId
     self.appId       = appId
     self.appPassword = appPassword
     self.aboutYouClient = AboutYou::SDK::Client.new(appId, appPassword, apiEndPoint, logger)
+    resultFactory ? self.modelFactoryInstance = resultFactory : initDefaultFactory(facetManagerCache)
 
     if apiEndPoint == AboutYou::SDK::Constants::API_ENVIRONMENT_STAGE
       self.baseImageUrl=(IMAGE_URL_STAGE)
@@ -53,17 +72,15 @@ class AY
    # Adds a single item into the basket.
    # You can specify an amount. Please mind, that an amount > 1 will result in #amount basket positions.
    # So if you read out the basket again later, it's your job to merge the positions again.
-   #
-   # It is highly recommend to use the basket update method, to manage your items.
-   #
-   # @param string $sessionId
-   # @param integer $variantId
-   # @param integer $amount
-   #
-   # @return Basket
-   #
-   # @throws \InvalidArgumentException
-   ##
+   # 
+   # * *Args*    :
+   #   - +sessionId+ -> A String containing the sessionId of the User
+   #   - +variantId+ -> The Id of the Variant which should be added to the basket
+   #   - +amount+ -> The Amount of the Item which should be added to the basket
+   #   
+   # * *Returns* :
+   #   - Instance of AboutYou::SDK::Model::Basket
+   ###
   def addItemToBasket(sessionId, variantId, amount = 1)
 
     basket = AboutYou::SDK::Model::Basket.new
@@ -76,7 +93,6 @@ class AY
       end
     end
 
-
     amount.times do
       basket.updateItem(AboutYou::SDK::Model::Basket::BasketItem.new(generateBasketItemId, variantId))
     end
@@ -84,7 +100,15 @@ class AY
     updateBasket(sessionId, basket)
   end
 
-
+  
+   ###
+   # Method to create a unique item id for items in basket
+   # 
+   # * *Args*    :
+   #   
+   # * *Returns* :
+   #   - an Intger
+   ###
   def generateBasketItemId
 
     'i_' + SecureRandom.uuid
@@ -92,12 +116,14 @@ class AY
 
 
    ###
-   # Remove basket item.
-   #
-   # @param string $sessionId     Free to choose ID of the current website visitor.
-   # @param string[] $itemIds     array of basket item ids to delete, this can be sets or single items
-   #
-   # @return \Collins\ShopApi\Model\Basket
+   # Method to remove items from basket
+   # 
+   # * *Args*    :
+   #   - +sessionId+ -> A String containing the sessionId of the User
+   #   - +itemIds+ -> an Array of Item ids which should be removed
+   #   
+   # * *Returns* :
+   #   - Instance of AboutYou::SDK::Model::Basket
    ###
   def removeItemsFromBasket(sessionId, itemIds)
 
@@ -109,10 +135,14 @@ class AY
 
 
    ###
-   # @param string $sessionId
-   # @param Basket $basket
-   #
-   # @return \Collins\ShopApi\Model\Basket
+   # Method to update a given basket
+   # 
+   # * *Args*    :
+   #   - +sessionId+ -> A String containing the sessionId of the User
+   #   - +basket+ -> an Instance of a basket
+   #   
+   # * *Returns* :
+   #   - Instance of AboutYou::SDK::Model::Basket
    ###
   def updateBasket(sessionId, basket)
 
@@ -121,12 +151,16 @@ class AY
 
 
    ###
-   # @param string $sessionId the session id
-   # @param string $successUrl callback URL if the order was OK
-   # @param string $cancelUrl callback URL if the order was canceled [optional]
-   # @param string $errorUrl callback URL if the order had any exceptions [optional]
-   #
-   # @return \Collins\ShopApi\Model\InitiateOrder
+   # Method to initiaite the order
+   # 
+   # * *Args*    :
+   #   - +sessionId+ -> A String containing the sessionId of the User
+   #   - +successUrl+ -> callback URL if the order was OK
+   #   - +cancelUrl+ -> callback URL if the order was canceled [optional]
+   #   - +errorUrl+ -> callback URL if the order had any exceptions [optional]
+   #   
+   # * *Returns* :
+   #   - Instance of AboutYou::SDK::Model::InitiateOrder
    ###
   def initiateOrder(sessionId,successUrl,cancelUrl = nil,errorUrl = nil)
 
@@ -137,13 +171,15 @@ class AY
    ###
    # Returns the result of an auto completion API request.
    # Auto completion searches for products and categories by
-   # a given prefix ($searchword).
-   #
-   # @param string $searchword The prefix search word to search for.
-   # @param int    $limit      Maximum number of results.
-   # @param array  $types      Array of types to search for (Constants::TYPE_...).
-   #
-   # @return \Collins\ShopApi\Model\Autocomplete
+   # a given prefix (searchword).
+   # 
+   # * *Args*    :
+   #   - +searchword+ -> The prefix search word to search for
+   #   - +limit+ -> Maximum number of results [optional]
+   #   - +types+ -> Array of types to search for [optional]
+   #   
+   # * *Returns* :
+   #   - Instance of AboutYou::SDK::Model::Automcomplete
    ###
    def fetchAutocomplete(searchword, limit = 50, types = [AboutYou::SDK::Constants::TYPE_PRODUCTS, AboutYou::SDK::Constants::TYPE_CATEGORIES])
 
@@ -153,13 +189,12 @@ class AY
 
    ###
    # Fetch the basket of the given sessionId.
-   #
-   # @param string $sessionId Free to choose ID of the current website visitor.
-   #
-   # @return \Collins\ShopApi\Model\Basket
-   #
-   # @throws ShopApi\Exception\MalformedJsonException
-   # @throws ShopApi\Exception\UnexpectedResultException
+   # 
+   # * *Args*    :
+   #   - +sessionId+ -> A String containing the sessionId of the User
+   #   
+   # * *Returns* :
+   #   - Instance of AboutYou::SDK::Model::Basket
    ###
   def fetchBasket(sessionId)
 
@@ -171,10 +206,12 @@ class AY
    # Returns the result of a category search API request.
    # By passing one or several category ids it will return
    # a result of the categories data.
-   #
-   # @param mixed $ids either a single category ID as integer or an array of IDs
-   #
-   # @return \Collins\ShopApi\Model\CategoriesResult
+   #  
+   # * *Args*    :
+   #   - +ids+ -> either a single category ID as integer or an array of IDs [optional]
+   #   
+   # * *Returns* :
+   #   - Instance of AboutYou::SDK::Model::CategoriesResult
    ###
   def fetchCategoriesByIds(ids = nil)
     # we allow to pass a single ID instead of an array
@@ -189,12 +226,10 @@ class AY
 
 
    ###
-   # @param int $maxDepth  -1 <= $maxDepth <= 10
-   #
-   # @return CategoryTree
-   #
-   # @throws ShopApi\Exception\MalformedJsonException
-   # @throws ShopApi\Exception\UnexpectedResultException
+   # Fetches the Root Categories of the Category Tree
+   # 
+   # * *Returns* :
+   #   - Instance of AboutYou::SDK::Model::CategoryTree
    ###
   def fetchCategoryTree
 
@@ -203,17 +238,13 @@ class AY
   
 
    ###
-   # The Categories will be fetch automatically, if required by any other fetch method
-   #
-   # For Example
-   # $productsResult = $api->fetchProductsByIds([12345], ['categories']);
-   #  will fetch the categories with the same request.
-   # $rootCategories = $api->getCategoryManager()->getCategoryTree();
-   #  will give you all categories for your Menu without an other request
-   #
-   # @param bool $fetchIfEmpty
-   #
-   # @return CategoryManagerInterface
+   # The Categories will be fetched automatically, if required by any other fetch method
+   #  
+   # * *Args*    :
+   #   - +fetchIfEmpty+ -> defines whether to fetch if empty or not [optional]
+   #   
+   # * *Returns* :
+   #   - Instance of AboutYou::SDK::CategoryManager::DefaultCategoryManager
    ###
   def categoryManager(fetchIfEmpty = true)
 
@@ -228,13 +259,14 @@ class AY
 
 
    ###
-   # @param integer[] $ids
-   # @param string[] $fields
-   #
-   # @return ProductsResult
-   #
-   # @throws ShopApi\Exception\MalformedJsonException
-   # @throws ShopApi\Exception\UnexpectedResultException
+   # Fetches the products for specific ids
+   #  
+   # * *Args*    :
+   #   - +ids+ -> Either a single id or an Array of ids which should be fetched
+   #   - +fields+ -> Additional product fields which should be fetched for each product [optional]
+   #   
+   # * *Returns* :
+   #   - Instance of AboutYou::SDK::Model::ProductsResult
    ###
   def fetchProductsByIds(ids , fields = [])
     # we allow to pass a single ID instead of an array
@@ -251,12 +283,13 @@ class AY
 
 
    ###
-   # @param integer[] $ids
-   #
-   # @return ShopApi\Model\VariantsResult
-   #
-   # @throws ShopApi\Exception\MalformedJsonException
-   # @throws ShopApi\Exception\UnexpectedResultException
+   # Fetches variants for specific ids
+   #  
+   # * *Args*    :
+   #   - +ids+ -> Either a single id or an Array of ids which should be fetched
+   #   
+   # * *Returns* :
+   #   - Instance of AboutYou::SDK::Model::VariantsResult
    ###
   def fetchVariantsByIds(ids) 
     # we allow to pass a single ID instead of an array
@@ -274,13 +307,14 @@ class AY
 
 
    ###
-   # @param string[] $eans
-   # @param string[] $fields
-   #
-   # @return ProductsEansResult
-   #
-   # @throws ShopApi\Exception\MalformedJsonException
-   # @throws ShopApi\Exception\UnexpectedResultException
+   # Fetches products for specific eans
+   #  
+   # * *Args*    :
+   #   - +eans+ -> Either a single ean or an Array of eans which should be fetched
+   #   - +fields+ -> Additional product fields which should be fetched for each product [optional]
+   #   
+   # * *Returns* :
+   #   - Instance of AboutYou::SDK::Model::ProductsEanResult
    ###
   def fetchProductsByEans(eans,fields = [])
   # we allow to pass a single ID instead of an array
@@ -292,12 +326,13 @@ class AY
 
 
    ###
-   # @param ProductSearchCriteria $criteria
-   #
-   # @return ProductSearchResult
-   #
-   # @throws ShopApi\Exception\MalformedJsonException
-   # @throws ShopApi\Exception\UnexpectedResultException
+   # Fetches the response for a product search
+   #  
+   # * *Args*    :
+   #   - +criteria+ -> Hash containing one or multiple search terms
+   #   
+   # * *Returns* :
+   #   - Instance of AboutYou::SDK::Model::ProductSearchResult
    ###
   def fetchProductSearch(criteria)
 
@@ -306,14 +341,13 @@ class AY
 
 
    ###
-   # Fetch the facets of the given groupIds.
-   #
-   # @param array $groupIds The group ids.
-   #
-   # @return \Collins\ShopApi\Model\Facet[] With facet id as key.
-   #
-   # @throws ShopApi\Exception\MalformedJsonException
-   #@throws ShopApi\Exception\UnexpectedResultException
+   # Fetch the facets of the given groupIds
+   #  
+   # * *Args*    :
+   #   - +groupIds+ -> Array of group ids [optional]
+   #   
+   # * *Returns* :
+   #   - Instance of AboutYou::SDK::Model::Facet
    ###
   def fetchFacets(groupIds=[])
 
@@ -321,6 +355,12 @@ class AY
   end
 
 
+   ###
+   # Fetches all possible Facet types
+   #   
+   # * *Returns* :
+   #   - Array with all group ids
+   ###  
   def fetchFacetTypes
     
     query.fetchFacetTypes.executeSingle
@@ -328,9 +368,12 @@ class AY
 
 
    ###
-   # @param string|integer $orderId the order id
-   #
-   # @return \Collins\ShopApi\Model\Order the order
+   # fetches Order for specific id
+   #  
+   # * *Args*    :
+   #   - +orderId+ -> The id for which an order should be returned
+   # * *Returns* :
+   #   - Instance of AboutYou::SDK::Model::Order
    ###
   def fetchOrder(orderId)
 
@@ -340,18 +383,12 @@ class AY
 
    ###
    # Fetch single facets by id and group id
-   # For example:
-   # $shopApi->fetchFacet([
-   #   ["id" => 123, "group_id" => 0 ],
-   #   ["id" => 456, "group_id" => 0 ]
-   # ])
-   #
-   # @param array $params Array of (id, group_id) pairs
-   #
-   # @return \Collins\ShopApi\Model\Facet[] With facet id as key.
-   #
-   # @throws ShopApi\Exception\MalformedJsonException
-   # @throws ShopApi\Exception\UnexpectedResultException
+   #  
+   # * *Args*    :
+   #   - +params+ -> Hash containing 2 keys: "id", "group_id"
+   #   
+   # * *Returns* :
+   #   - AboutYou::SDK::Model::Facet
    ###
   def fetchFacet(params)
 
@@ -363,10 +400,11 @@ class AY
    # Returns the result of a suggest API request.
    # Suggestions are words that are often searched together
    # with the searchword you pass (e.g. "stretch" for "jeans").
-   #
-   # @param string $searchword The search string to search for.
-   #
-   # @return array
+   #  
+   # * *Args*    :
+   #   - +searchword+ -> The search string to search for
+   # * *Returns* :
+   #   - an Array containing the suggestions
    ###
   def fetchSuggest(searchword)
 
@@ -377,20 +415,33 @@ class AY
    ###
    # Returns the list of child apps
    #
-   # @return array
+   # * *returns*  :
+   #   - an Array containing all child Apps
    ###
   def fetchChildApps
 
     query.fetchChildApps.executeSingle
   end
 
-
+  
+   ###
+   # Method for getting the query
+   #  
+   # * *Returns* :
+   #   - an Instance of AboutYou::SDK::Query
+   ###
   def query
 
     AboutYou::SDK::Query.new(self.aboutYouClient, modelFactory)
   end
 
   
+   ###
+   # Method for getting the model factory. If no model factory is set it initializes the default one
+   #  
+   # * *Returns* :
+   #   - an Instance of AboutYou::SDK::Factory::DefaultModelFactory
+   ###
   def modelFactory
 
     unless self.modelFactoryInstance
@@ -402,9 +453,12 @@ class AY
 
   
    ###
-   # @param string|nil $sessionId
-   #
-   # @return ProductSearchCriteria
+   # Method for getting the product search criteria base class, on which you can specify your criteria
+   #  
+   # * *Args*    :
+   #   - +sessionId+ -> a string containing the session id [optional]
+   # * *Returns* :
+   #   - AboutYou::SDK::Criteria::ProductSearchCriteria
    ###
   def productSearchCriteria(sessionId=nil)
     unless sessionId 
@@ -420,8 +474,9 @@ class AY
    # to add product variants into the basket of Mary & Paul or auto-resizing
    # the Iframe. This URL may be changed in future, so please use this method instead
    # of hardcoding the URL into your HTML template.
-   #
-   # @return string URL to the JavaScript file
+   #  
+   # * *Returns* :
+   #   - a string containing an url to the javascript file
    ###
   def javaScriptURL
 
@@ -436,7 +491,8 @@ class AY
    ###
    # Returns a HTML script tag that loads the Collins JavaScript fie.
    #
-   # @return string HTML script tag
+   # * *Returns* :
+   #   - a string containing an HTML script tag
    ###
   def javaScriptTag
 
@@ -445,8 +501,11 @@ class AY
 
 
    ###
-   # @param string $appId        the app id for client authentication
-   # @param string $appPassword  the app password/token for client authentication.
+   # Setter-Method for the app-Credentials
+   #  
+   # * *Args*    :
+   #   - +appId+ -> the id of an app
+   #   - +appPassword+ -> the auth-token for the app
    ###
   def appCredentials=(appId, appPassword)
 
@@ -458,7 +517,10 @@ class AY
 
 
    ###
-   # @param string $apiEndPoint the endpoint can be the string 'stage' or 'live',
+   # Setter-Method for the api endpoint
+   #  
+   # * *Args*    :
+   #   - +apiEndPoint+ -> the endpoint can be the string 'stage' or 'live',
    #                            then the default endpoints will be used or
    #                            an absolute url
    ###
@@ -469,7 +531,10 @@ class AY
 
 
    ###
-   # @param null|false|string $baseImageUrl null will reset to the default url, false to get relative urls, otherwise the url prefix
+   # Setter-Method for the base image url
+   # 
+   # * *Args*    :
+   #   - +baseImageUrl+ -> nil will reset to the default url, false to get relative urls, otherwise the url prefix
    ###
   def baseImageUrl=(baseImageUrl = nil)
 
@@ -483,7 +548,14 @@ class AY
 
     self.modelFactory.baseImageUrl=(self.baseImageUrl)
   end
-
+  
+  
+   ###
+   # initializes the default model factory
+   # 
+   # * *Args*    :
+   #   - +cache+ -> an Instance of the used cache [optional]
+   ###
   def initDefaultFactory(cache = nil)
 
     resultFactory = AboutYou::SDK::Factory::DefaultModelFactory.new(self,

data/lib/aboutyou-sdk/Client.rb

@@ -1,5 +1,10 @@
 module AboutYou
   module SDK
+    ###
+    # This Class manages the API-Calls
+    # 
+    # Author:: Collins GmbH & Co KG
+    ###
     class Client
 
       API_END_POINT_STAGE   = 'http://shop-api.staging.aboutyou.de/api'
@@ -11,6 +16,19 @@ module AboutYou
       attr_accessor :apiEndPoint
       attr_accessor :pageId
 
+      
+      ###
+      # the Constructor for the Client class
+      #
+      # * *Args*    :
+      #   - +appId+ -> The App-Id of the App
+      #   - +appPassword+ -> The Auth-Token of the App
+      #   - +apiEndPoint+ -> Can be either live or staging
+      #   - +logger+ -> Logger-Template
+      #   
+      # * *Returns* :
+      #   - Instance of AboutYou::SDK::Client
+      ###
       def initialize(appId, appPassword, apiEndPoint = 'stage', logger = nil)
 
         self.appId = appId
@@ -19,8 +37,11 @@ module AboutYou
 
 
        ###
-       # @param appId        the app id for client authentication
-       # @param appPassword  the app password/token for client authentication.
+       # Setter for app-credentials
+       #
+       # * *Args*    :
+       #   - +appId+ -> The App-Id of the App
+       #   - +appPassword+ -> The Auth-Token of the App
        ###
       def appCredentials=(appId, appPassword)
 
@@ -30,9 +51,10 @@ module AboutYou
 
 
        ###
-       # @param apiEndPoint the endpoint can be the string 'stage' or 'live',
-       #                    then the default endpoints will be used or
-       #                    an absolute url
+       # Setter for the api endpoint
+       #
+       # * *Args*    :
+       #   - +apiEndPoint+ -> Can be either live or staging
        ###
       def apiEndpoint=(apiEndPoint)
 
@@ -50,10 +72,15 @@ module AboutYou
 
 
        ###
-       # Builds a JSON string representing the request data via Guzzle.
-       # Executes the API request.
+       # Builds a JSON string representing the request-data
+       # Executes the API request
+       # builds a JSON string representing the response-data
+       # 
+       # * *Args*    :
+       #   - +body+ -> the body of the api-call, containing all request data
        #
-       # @param body the queries as json string
+       # * *Returns* :
+       #   - Json-String containing the response-body
        ###
       def request(body)
 

data/lib/aboutyou-sdk/Constants.rb

@@ -1,10 +1,10 @@
- ###
- # Contains often used properties related to the App development.
- #
- # @author Antevorte GmbH
- ###
 module AboutYou
   module SDK
+    ###
+    # Contains often used properties related to the App development.
+    #
+    # Author:: Collins GmbH & Co KG
+    ###
     module Constants
         SDK_VERSION = 0.1
         FACET_BRAND = 0

data/lib/aboutyou-sdk/Model/Category.rb

@@ -6,7 +6,6 @@ module AboutYou
           ACTIVE_ONLY = true;
 
           # @var integer */
-          @id;
           attr_accessor :id
 
           # @var string */
@@ -62,7 +61,7 @@ module AboutYou
               category.isActive = jsonObject["active"];
               category.position = jsonObject["position"];
               category.categoryManager = catManager
-              
+                            
               return category;
           end
 
@@ -89,6 +88,7 @@ module AboutYou
 
             return self.categoryManager.category(self.parentId);
           end
+          
 
            ###
            # @param bool $activeOnly

data/lib/aboutyou-sdk/Query.rb

@@ -2,6 +2,11 @@ require_relative 'QueryBuilder.rb'
 
 module AboutYou
   module SDK
+     ###
+     # The Query class coordinates the building, executing and parsing of one or multiple API-calls
+     #
+     # Author:: Collins GmbH & Co KG
+     ###
     class Query
       include AboutYou::SDK::QueryBuilder
       
@@ -16,6 +21,16 @@ module AboutYou
       attr_accessor :allQuery
 
 
+       ###
+       # the Constructor for the Query class
+       #
+       # * *Args*    :
+       #   - +client+ -> an instance of AboutYou::SDK::Client
+       #   - +factory+ -> an instance of AboutYou::SDK::Factory::DefaultModelFactory
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
+       ###      
       def initialize(client, factory)
         self.client = client
         self.query= []
@@ -42,13 +57,15 @@ module AboutYou
       end
 
        ###
-       # @param string $searchword The prefix search word to search for.
-       # @param int    $limit      Maximum number of results.
-       # @param array  $types      Array of types to search for (Constants::TYPE_...).
-       #
-       # @return $this
+       # wrapper-method for fetchAutocomplete which coordinates Category- and Facet-Manager
        #
-       # @throws \InvalidArgumentException
+       # * *Args*    :
+       #   - +searchword+ -> a String containing the word to search completitions for
+       #   - +limit+ -> Maximum number of results [optional]
+       #   - +types+ -> Array of types to search for [optional]
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchAutocomplete(searchword, limit = nil, types = nil)
 
@@ -61,9 +78,13 @@ module AboutYou
       end
 
        ###
-       # @param string $sessionId Free to choose ID of the current website visitor.
+       # wrapper-method for fetchBasket which coordinates Category- and Facet-Manager
        #
-       # @return $this
+       # * *Args*    :
+       #   - +sessionId+ -> a String containing the session id of an user
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchBasket(sessionId)
 
@@ -76,10 +97,14 @@ module AboutYou
       end
 
        ###
-       # @param string[]|int[] $ids
-       # @param array $fields
+       # wrapper-method for fetchProductsByIds which coordinates Category- and Facet-Manager
        #
-       # @return $this
+       # * *Args*    :
+       #   - +ids+ -> Either a single id or an Array of ids which should be fetched
+       #   - +fields+ -> Additional product fields which should be fetched for each product [optional]
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchProductsByIds(ids,fields = [])
         
@@ -96,10 +121,14 @@ module AboutYou
       end
 
        ###
-       # @param string[] $eans
-       # @param array $fields
+       # wrapper-method for fetchProductsByEans which coordinates Category- and Facet-Manager
        #
-       # @return $this
+       # * *Args*    :
+       #   - +eans+ -> Either a single ean or an Array of eans which should be fetched
+       #   - +fields+ -> Additional product fields which should be fetched for each product [optional]
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchProductsByEans(eans,fields = [])
         
@@ -116,9 +145,13 @@ module AboutYou
       end
 
        ###
-       # @param ProductSearchCriteria $criteria
+       # wrapper-method for fetchProductSearch which coordinates Category- and Facet-Manager
        #
-       # @return $this
+       # * *Args*    :
+       #   - +criteria+ -> Hash containing one or multiple search terms
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchProductSearch(criteria)
 
@@ -133,7 +166,17 @@ module AboutYou
 
         return self
       end
+      
 
+       ###
+       # this method checks whether it is neccessary for the query to get the category-tree from the api
+       #
+       # * *Args*    :
+       #   - +fetchForced+ -> determines whether the requirance of the category tree is forced
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
+       ###      
       def requireCategoryTree(fetchForced = false)
         
         unless fetchForced || self.factory.categoryManager.isEmpty
@@ -148,6 +191,16 @@ module AboutYou
          return self
       end
 
+      
+       ###
+       # this method checks whether it is neccessary for the query to get the facets from the api
+       #
+       # * *Args*    :
+       #   - +fetchForced+ -> determines whether the requirance of the facets is forced
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
+       ###          
       def requireFacets(fetchForced = false)
         unless fetchForced || self.factory.facetManager.isEmpty
             return self
@@ -160,8 +213,11 @@ module AboutYou
       end
 
        ###
-       # @return string
-       ###
+       # the methods builds the complete query string which represents the body of the api call
+       #   
+       # * *Returns* :
+       #   - JSON-String containing all queries which need to be executed
+       ###    
       def queryString
         result = []
         self.ghostQuery.each do |ghostQuery|
@@ -173,10 +229,11 @@ module AboutYou
 
 
        ###
-       # request the queries and returns an array of the results
-       #
-       # @return array
-       ###
+       # requests all of the queries and returns the parsed api-response
+       #   
+       # * *Returns* :
+       #   - an Array containing all of the models build with the data of the api 
+       ###    
       def execute
 
         if self.query.empty? && self.ghostQuery.empty? 
@@ -186,15 +243,23 @@ module AboutYou
       end
 
        ###
-       # request the current query and returns the first result
-       #
-       # @return mixed
+       # requests all of the queries and returns only the first parsed api-response
+       #   
+       # * *Returns* :
+       #   - the first model build with the data of the api 
        ###
       def executeSingle
 
         execute[-1]
       end
 
+      
+       ###
+       # this method checks whether the api delievered a valid json-response or not
+       # 
+       # * *Args*    :
+       #   - +jsonResponse+ -> the plain json received from the api
+       ###      
       def checkResponse(jsonResponse)
 
         if jsonResponse == false || !(jsonResponse.is_a? Array) || jsonResponse.count != self.allQuery.count
@@ -217,7 +282,20 @@ module AboutYou
           end
         end
       end
-
+      
+      
+       ###
+       # parses the plain json result from the api and calls the respective modelfactory methods 
+       # for building the models for the json resposne
+       # 
+       # * *Args*    :
+       #   - +jsonResponse+ -> the plain json received from the api
+       #   - +isMultiRequest+ -> boolean which determines whether the request has more then one
+       #                         query or not [optional]
+       #   
+       # * *Returns* :
+       #   - an Array containing all models build from the modelfactory 
+       ###     
       def parseResult(jsonResponse, isMultiRequest=true)
 
         self.checkResponse(jsonResponse)

data/lib/aboutyou-sdk/QueryBuilder.rb

@@ -1,15 +1,23 @@
 module AboutYou
   module SDK
+    ###
+    # the QueryBuilder is a module supporting the query with mroe complex logic
+    # concerning the building of the queries for the api-call
+    #
+    # Author:: Collins GmbH & Co KG
+    ###
     module QueryBuilder
 
        ###
-       # @param string $searchword The prefix search word to search for.
-       # @param int    $limit      Maximum number of results.
-       # @param array  $types      Array of types to search for (Constants::TYPE_...).
-       #  
-       # @return $this
+       # builds the autocompletion-query
        #
-       # @throws \InvalidArgumentException
+       # * *Args*    :
+       #   - +searchword+ -> a String containing the word to search completitions for
+       #   - +limit+ -> Maximum number of results [optional]
+       #   - +types+ -> Array of types to search for [optional]
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchAutocomplete(searchword, limit = nil, types = nil)
 
@@ -36,9 +44,13 @@ module AboutYou
       end
 
        ###
-       # @param string $sessionId Free to choose ID of the current website visitor.
+       # builds the basket-query
        #
-       # @return $this
+       # * *Args*    :
+       #   - +sessionId+ -> a String containing the session id of an user
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchBasket(sessionId)
 
@@ -49,11 +61,14 @@ module AboutYou
       end
 
        ###
-       # @param string $sessionId        Free to choose ID of the current website visitor.
-       # @param int    $productVariantId ID of product variant.
-       # @param int    $amount           Amount of items to add.
+       # builds the basket-query
        #
-       #@return $this
+       # * *Args*    :
+       #   - +sessionId+ -> a String containing the session id of an user
+       #   - +items+ -> an Array containing all of the items which should be added
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def addItemsToBasket(sessionId, items)
 
@@ -82,11 +97,14 @@ module AboutYou
       end
 
        ###
-       # @param string $sessionId        Free to choose ID of the current website visitor.
-       # @param Model\BasketItemSet[]    $itemSets
-       # @param int    $amount           Amount of items to add.
+       # builds the basket-query
        #
-       # @return $this
+       # * *Args*    :
+       #   - +sessionId+ -> a String containing the session id of an user
+       #   - +itemSets+ -> an instance of AboutYou::SDK::Model::BasketSet
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def addItemSetsToBasket(sessionId, itemSets)
 
@@ -123,15 +141,19 @@ module AboutYou
       end
 
        ###
-       # @param string $sessionId        Free to choose ID of the current website visitor.
-       # @param int    $productVariantId ID of product variant.
-       # @param string $basketItemId  ID of single item or set in the basket
+       # builds the basket-query
        #
-       # @return $this
+       # * *Args*    :
+       #   - +sessionId+ -> a String containing the session id of an user
+       #   - +productVariantId+ -> ID of product variant
+       #   - +basketItemId+ -> ID of single item or set in the basket
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def addToBasket(sessionId, productVariantId, basketItemId)
 
-        checkSessionId(sessionId);
+        checkSessionId(sessionId)
 
         self.query.push({'basket' => {
           'session_id' => sessionId,
@@ -144,10 +166,14 @@ module AboutYou
       end
 
        ###
-       # @param string   $sessionId   Free to choose ID of the current website visitor.
-       # @param string[] $itemIds     array of basket item ids to delete, this can be sets or single items
+       # builds the basket-query
        #
-       # @return $this
+       # * *Args*    :
+       #   - +sessionId+ -> a String containing the session id of an user
+       #   - +itemIds+ -> array of basket item ids to delete, this can be sets or single items
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def removeFromBasket(sessionId, itemIds)
 
@@ -169,10 +195,14 @@ module AboutYou
       end
 
        ###
-       # @param string $sessionId
-       # @param Basket $basket
+       # builds the basket-query
        #
-       # @return $this
+       # * *Args*    :
+       #   - +sessionId+ -> a String containing the session id of an user
+       #   - +basket+ -> an instance of AboutYou::SDK::Model::Basket
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def updateBasket(sessionId, basket)
 
@@ -190,9 +220,13 @@ module AboutYou
       end
 
        ###
-       # @param int[]|string[] $ids either a single category ID as integer or an array of IDs
+       # builds the category-query
        #
-       # @return $this
+       # * *Args*    :
+       #   - +ids+ -> either a single category ID as integer or an array of IDs
+       #   
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchCategoriesByIds(ids = nil)
        
@@ -220,21 +254,26 @@ module AboutYou
       end
 
        ###
-       # @param int $maxDepth -1 <= $maxDepth <= 10,
+       # builds the category_tree-query
        #
-       # @return $this
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
-      def fetchCategoryTree()
+      def fetchCategoryTree
 
         self.query.push({'category_tree' => {"version"=>"2"}})
         self
       end
 
        ###
-       # @param string[]|int[] $ids
-       # @param array $fields
+       # builds the products-query
        #
-       # @return $this
+       # * *Args*    :
+       #   - +ids+ -> Either a single id or an Array of ids which should be fetched
+       #   - +fields+ -> Additional product fields which should be fetched for each product [optional]
+       #      
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchProductsByIds(ids,fields = [])
         # we allow to pass a single ID instead of an array
@@ -250,9 +289,13 @@ module AboutYou
       end
 
        ###
-       # @param string[]|int[] $ids
+       # builds the live_variant-query
        #
-       # @return $this
+       # * *Args*    :
+       #   - +ids+ -> Either a single id or an Array of ids which should be fetched
+       #      
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchLiveVariantByIds(ids) 
         # we allow to pass a single ID instead of an array
@@ -265,10 +308,14 @@ module AboutYou
       end
 
        ###
-       # @param string[] $eans
-       # @param array $fields
+       # builds the products_eans-query
        #
-       # @return $this
+       # * *Args*    :
+       #   - +eans+ -> Either a single ean or an Array of eans which should be fetched
+       #   - +fields+ -> Additional product fields which should be fetched for each product [optional]
+       #     
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchProductsByEans(eans,fields = [])
         
@@ -283,9 +330,13 @@ module AboutYou
       end
 
        ###
-       # @param string|int $orderId
+       # builds the get_order-query
        #
-       # @return $this
+       # * *Args*    :
+       #   - +orderId+ -> id of the order which should be fetched
+       #     
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchOrder(orderId)
 
@@ -294,12 +345,16 @@ module AboutYou
       end
 
        ###
-       # @param string $sessionId
-       # @param string $successUrl
-       # @param string $cancelUrl
-       # @param string $errorUrl
+       # builds the initiate_order-query
        #
-       # @return $this
+       # * *Args*    :
+       #   - +sessionId+ -> A String containing the sessionId of the User
+       #   - +successUrl+ -> callback URL if the order was OK
+       #   - +cancelUrl+ -> callback URL if the order was canceled [optional]
+       #   - +errorUrl+ -> callback URL if the order had any exceptions [optional]
+       #     
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def initiateOrder(sessionId, successUrl, cancelUrl, errorUrl)
 
@@ -320,9 +375,13 @@ module AboutYou
       end
 
        ###
-       # @param ProductSearchCriteria $criteria
+       # builds the product_search-query
        #
-       # @return $this
+       # * *Args*    :
+       #   - +criteria+ -> Hash containing one or multiple search terms
+       #     
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchProductSearch(criteria)
 
@@ -333,11 +392,13 @@ module AboutYou
       end
 
        ###
-       # @param array $groupIds
-       #
-       # @return $this
+       # builds the facets-query
        #
-       # @throws \InvalidArgumentException
+       # * *Args*    :
+       #   - +groupIds+ -> Array of group ids [optional]
+       #     
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchFacets(groupIds = [])
 
@@ -350,11 +411,13 @@ module AboutYou
       end
 
        ###
-       # @param array $params
-       #
-       # @return $this
+       # builds the facet-query
        #
-       # @throws \InvalidArgumentException
+       # * *Args*    :
+       #   - +params+ -> Hash containing 2 keys: "id", "group_id"
+       #     
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchFacet(params)
 
@@ -367,7 +430,10 @@ module AboutYou
       end
 
        ###
-       # @return $this
+       # builds the facet_types-query
+       #     
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchFacetTypes
 
@@ -376,9 +442,13 @@ module AboutYou
       end
 
        ###
-       # @param string $searchword The search string to search for.
+       # builds the suggest-query
        #
-       # @return $this
+       # * *Args*    :
+       #   - +searchword+ -> the searchs tring to search for
+       #     
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchSuggest(searchword)
 
@@ -387,7 +457,10 @@ module AboutYou
       end
 
        ###
-       # @return $this
+       # builds the child_apps-query
+       #     
+       # * *Returns* :
+       #   - Instance of AboutYou::SDK::Query
        ###
       def fetchChildApps
 
@@ -396,7 +469,10 @@ module AboutYou
       end
 
        ###
-       # @return string
+       # turns all queries built in here into a json string
+       #     
+       # * *Returns* :
+       #   - Json string containing all queries built in here
        ###
       def queryString
 
@@ -404,9 +480,10 @@ module AboutYou
       end
 
        ###
-       # @param $sessionId
+       # checks whether the session id is valid or not
        #
-       # @throws \InvalidArgumentException
+       # * *Args*    :
+       #   - +sessionId+ -> the session id of a user
        ###
       def checkSessionId(sessionId)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: aboutyou-sdk
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
 platform: ruby
 authors:
 - Ferenc Beutel