recombee_api_client 0.1.0

data/lib/recombee_api_client/api/remove_from_group.rb

@@ -0,0 +1,59 @@
+#
+# This file is auto-generated, do not edit
+#
+
+module RecombeeApiClient
+  require_relative 'request'
+  require_relative '../errors'
+  
+  ##
+  #Removes an existing group item from the group.
+  class RemoveFromGroup < ApiRequest
+    attr_reader :group_id, :item_type, :item_id
+    attr_accessor :timeout
+  
+  ##
+  # * *Required arguments*
+  #   - +group_id+ -> ID of the group from which a group item is to be removed.
+  #   - +item_type+ -> Type of the item to be removed.
+  #   - +item_id+ -> ID of the item iff `itemType` is `item`. ID of the group iff `itemType` is `group`.
+  #
+    def initialize(group_id, item_type, item_id)
+      @group_id = group_id
+      @item_type = item_type
+      @item_id = item_id
+      @timeout = 1000
+    end
+  
+    # HTTP method
+    def method
+      :delete
+    end
+  
+    # Values of body parameters as a Hash
+    def body_parameters
+      p = Hash.new
+      p
+    end
+  
+    # Values of query path parameters as a Hash.
+    # name of parameter => value of the parameter
+    def query_parameters
+      params = {}
+      params['itemType'] = @item_type
+      params['itemId'] = @item_id
+      params
+    end
+  
+    # Relative path to the endpoint
+    def basic_path
+      "/{databaseId}/groups/#{@group_id}/items/"
+    end
+  
+    # Relative path to the endpoint including query parameters
+    def path
+      p = "/{databaseId}/groups/#{@group_id}/items/?itemType=#{@item_type}&itemId=#{@item_id}"
+      p
+    end
+  end
+end

data/lib/recombee_api_client/api/remove_from_series.rb

@@ -0,0 +1,62 @@
+#
+# This file is auto-generated, do not edit
+#
+
+module RecombeeApiClient
+  require_relative 'request'
+  require_relative '../errors'
+  
+  ##
+  #Removes an existing series item from the series.
+  class RemoveFromSeries < ApiRequest
+    attr_reader :series_id, :item_type, :item_id, :time
+    attr_accessor :timeout
+  
+  ##
+  # * *Required arguments*
+  #   - +series_id+ -> ID of the series from which a series item is to be removed.
+  #   - +item_type+ -> Type of the item to be removed.
+  #   - +item_id+ -> ID of the item iff `itemType` is `item`. ID of the series iff `itemType` is `series`.
+  #   - +time+ -> Time index of the item to be removed.
+  #
+    def initialize(series_id, item_type, item_id, time)
+      @series_id = series_id
+      @item_type = item_type
+      @item_id = item_id
+      @time = time
+      @timeout = 1000
+    end
+  
+    # HTTP method
+    def method
+      :delete
+    end
+  
+    # Values of body parameters as a Hash
+    def body_parameters
+      p = Hash.new
+      p
+    end
+  
+    # Values of query path parameters as a Hash.
+    # name of parameter => value of the parameter
+    def query_parameters
+      params = {}
+      params['itemType'] = @item_type
+      params['itemId'] = @item_id
+      params['time'] = @time
+      params
+    end
+  
+    # Relative path to the endpoint
+    def basic_path
+      "/{databaseId}/series/#{@series_id}/items/"
+    end
+  
+    # Relative path to the endpoint including query parameters
+    def path
+      p = "/{databaseId}/series/#{@series_id}/items/?itemType=#{@item_type}&itemId=#{@item_id}&time=#{@time}"
+      p
+    end
+  end
+end

data/lib/recombee_api_client/api/request.rb

@@ -0,0 +1,7 @@
+module RecombeeApiClient
+  ##
+  # Parent class for API requests
+  #
+  class ApiRequest
+  end
+end

data/lib/recombee_api_client/api/reset_database.rb

@@ -0,0 +1,51 @@
+#
+# This file is auto-generated, do not edit
+#
+
+module RecombeeApiClient
+  require_relative 'request'
+  require_relative '../errors'
+  
+  ##
+  #Completely erases all your data, including items, item properties, series, user database, purchases, ratings, detail views, and bookmarks. Make sure the request to be never executed in production environment! Resetting your database is irreversible.
+  #
+  class ResetDatabase < ApiRequest
+  
+    attr_accessor :timeout
+  
+  ##
+  #
+    def initialize()
+      @timeout = 3000
+    end
+  
+    # HTTP method
+    def method
+      :delete
+    end
+  
+    # Values of body parameters as a Hash
+    def body_parameters
+      p = Hash.new
+      p
+    end
+  
+    # Values of query path parameters as a Hash.
+    # name of parameter => value of the parameter
+    def query_parameters
+      params = {}
+      params
+    end
+  
+    # Relative path to the endpoint
+    def basic_path
+      "/{databaseId}/"
+    end
+  
+    # Relative path to the endpoint including query parameters
+    def path
+      p = "/{databaseId}/"
+      p
+    end
+  end
+end

data/lib/recombee_api_client/api/set_item_values.rb

@@ -0,0 +1,70 @@
+#
+# This file is auto-generated, do not edit
+#
+
+module RecombeeApiClient
+  require_relative 'request'
+  require_relative '../errors'
+  
+  ##
+  #Set/update (some) property values of a given item.
+  #
+  class SetItemValues < ApiRequest
+    attr_reader :item_id, :values
+    attr_accessor :timeout
+  
+  ##
+  # * *Required arguments*
+  #   - +item_id+ -> ID of the item which will be modified.
+  #
+  #   - +values+ -> The values for the individual properties.
+  #
+  #Example of body:
+  #```
+  #  {
+  #    "string_property": "strvalue",
+  #    "integer_property": 42,
+  #    "!cascadeCreate": true
+  #  }
+  #```
+  #
+  #Special parameter `!cascadeCreate` may be used. It indicates that the item of the given itemId should be created if it does not exist in the database, as if the corresponding PUT method was used. Note the exclamation mark (!) at the beginning of the parameter's name to distinguish it from item property names.
+  #
+  #
+    def initialize(item_id, values)
+      @item_id = item_id
+      @values = values
+      @timeout = 1000
+    end
+  
+    # HTTP method
+    def method
+      :post
+    end
+  
+    # Values of body parameters as a Hash
+    def body_parameters
+      p = Hash.new
+      p = p.merge(@values)
+      p
+    end
+  
+    # Values of query path parameters as a Hash.
+    # name of parameter => value of the parameter
+    def query_parameters
+      params = {}
+      params
+    end
+  
+    # Relative path to the endpoint
+    def basic_path
+      "/{databaseId}/items/#{@item_id}"
+    end
+  
+    # Relative path to the endpoint including query parameters
+    def path
+      p = "/{databaseId}/items/#{@item_id}"
+      p
+    end
+  end
+end

data/lib/recombee_api_client/api/user_based_recommendation.rb

@@ -0,0 +1,116 @@
+#
+# This file is auto-generated, do not edit
+#
+
+module RecombeeApiClient
+  require_relative 'request'
+  require_relative '../errors'
+  
+  ##
+  #Based on user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for a given user.
+  #
+  class UserBasedRecommendation < ApiRequest
+    attr_reader :user_id, :count, :filter, :booster, :allow_nonexistent, :diversity, :min_relevance, :rotation_rate, :rotation_time
+    attr_accessor :timeout
+  
+  ##
+  # * *Required arguments*
+  #   - +user_id+ -> ID of the user whose personalized recommendations are to be generated.
+  #   - +count+ -> Number of items to be recommended (N for the top-N recommendation).
+  #
+  # * *Optional arguments (given as hash optional)*
+  #   - +filter+ -> Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended items based on the values of their attributes.
+  #   - +booster+ -> Number-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to boost recommendation rate of some items based on the values of their attributes.
+  #   - +allowNonexistent+ -> If the user does not exist in the database, returns a list of non-personalized recommendations instead of causing HTTP 404 error.
+  #   - +diversity+ -> **Expert option** Real number from [0.0, 1.0] which determines how much mutually dissimilar should the recommended items be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification.
+  #
+  #   - +minRelevance+ -> **Expert option** Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend number of items equal to *count* at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested qualit, and may return less than *count* items when there is not enough data to fulfill it.
+  #
+  #   - +rotationRate+ -> **Expert option** If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example `rotationRate=0.2` for only slight rotation of recommended items.
+  #
+  #   - +rotationTime+ -> **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an item to fully recover from the penalization. By example, `rotationTime=7200.0` means that items recommended more than 2 hours ago are definitely not penalized anymore. Currently, the penalization is linear, so for `rotationTime=7200.0`, an item is still penalized by `0.5` to the user after 1 hour. |
+  #
+  #
+    def initialize(user_id, count, optional = {})
+      @user_id = user_id
+      @count = count
+      @filter = optional['filter']
+      @booster = optional['booster']
+      @allow_nonexistent = optional['allowNonexistent']
+      @diversity = optional['diversity']
+      @min_relevance = optional['minRelevance']
+      @rotation_rate = optional['rotationRate']
+      @rotation_time = optional['rotationTime']
+      @optional = optional
+      @timeout = 3000
+      @optional.each do |par, _|
+        fail UnknownOptionalParameter.new(par) unless ["filter","booster","allowNonexistent","diversity","minRelevance","rotationRate","rotationTime"].include? par
+      end
+    end
+  
+    # HTTP method
+    def method
+      :get
+    end
+  
+    # Values of body parameters as a Hash
+    def body_parameters
+      p = Hash.new
+      p
+    end
+  
+    # Values of query path parameters as a Hash.
+    # name of parameter => value of the parameter
+    def query_parameters
+      params = {}
+      params['count'] = @count
+      params['filter'] = @optional['filter'] if @optional['filter']
+      params['booster'] = @optional['booster'] if @optional['booster']
+      params['allowNonexistent'] = @optional['allowNonexistent'] if @optional['allowNonexistent']
+      params['diversity'] = @optional['diversity'] if @optional['diversity']
+      params['minRelevance'] = @optional['minRelevance'] if @optional['minRelevance']
+      params['rotationRate'] = @optional['rotationRate'] if @optional['rotationRate']
+      params['rotationTime'] = @optional['rotationTime'] if @optional['rotationTime']
+      params
+    end
+  
+    # Relative path to the endpoint
+    def basic_path
+      "/{databaseId}/users/#{@user_id}/recomms/"
+    end
+  
+    # Relative path to the endpoint including query parameters
+    def path
+      p = "/{databaseId}/users/#{@user_id}/recomms/?count=#{@count}"
+      if @optional.include? 'filter'
+        p += (p.include? '?') ? '&' : '?'
+        p += "filter=#{@optional['filter']}"
+      end
+      if @optional.include? 'booster'
+        p += (p.include? '?') ? '&' : '?'
+        p += "booster=#{@optional['booster']}"
+      end
+      if @optional.include? 'allowNonexistent'
+        p += (p.include? '?') ? '&' : '?'
+        p += "allowNonexistent=#{@optional['allowNonexistent']}"
+      end
+      if @optional.include? 'diversity'
+        p += (p.include? '?') ? '&' : '?'
+        p += "diversity=#{@optional['diversity']}"
+      end
+      if @optional.include? 'minRelevance'
+        p += (p.include? '?') ? '&' : '?'
+        p += "minRelevance=#{@optional['minRelevance']}"
+      end
+      if @optional.include? 'rotationRate'
+        p += (p.include? '?') ? '&' : '?'
+        p += "rotationRate=#{@optional['rotationRate']}"
+      end
+      if @optional.include? 'rotationTime'
+        p += (p.include? '?') ? '&' : '?'
+        p += "rotationTime=#{@optional['rotationTime']}"
+      end
+      p
+    end
+  end
+end

data/lib/recombee_api_client/errors.rb

@@ -0,0 +1,44 @@
+module RecombeeApiClient
+  # Errors in API
+  class APIError < StandardError
+  end
+
+  # Response is not 200 or 201
+  class ResponseError < APIError
+    attr_reader :request
+    attr_reader :status_code
+    attr_reader :description
+
+    def initialize(request, status_code, description)
+      @status_code = status_code
+      @description = description
+    end
+
+    def to_s
+      "ResponseError: status: #{@status_code}, description: #{@description}"
+    end
+  end
+
+  class UnknownOptionalParameter < StandardError
+    def initialize(parameter)
+      @parameter = parameter
+    end
+
+    def to_s
+      "UnknownOptionalParameter: unknown parameter #{@parameter} was given to the request"
+    end
+  end
+
+  class ApiTimeout < APIError
+    attr_reader :request
+
+    def initialize(request)
+      @request = request
+    end
+
+    def to_s
+      "ApiTimeout: client did not get response within #{@request.timeout} ms"
+    end
+  end
+
+end

data/lib/recombee_api_client/version.rb

@@ -0,0 +1,3 @@
+module RecombeeApiClient
+  VERSION = '0.1.0'
+end

data/lib/recombee_api_client.rb

@@ -0,0 +1,105 @@
+require 'recombee_api_client/version'
+require 'securerandom'
+require 'digest/hmac'
+require 'httparty'
+require 'json'
+require 'open-uri'
+require 'net/https'
+require 'timeout'
+
+require 'recombee_api_client/errors'
+Gem.find_files('recombee_api_client/api/*.rb').each { |path| require path }
+
+module RecombeeApiClient
+  class RecombeeClient
+    include HTTParty
+
+    def initialize(account, token, options = {})
+      @account = account
+      @token = token
+      @base_uri = options[:base_uri] ||= 'https://rapi.recombee.com'
+    end
+
+    def send(request)
+      @request = request
+      uri = request.path
+      uri.slice! ('/{databaseId}/')
+      uri = URI.escape uri
+      timeout = request.timeout / 1000
+      # puts uri
+      begin
+        case request.method
+        when :put
+          hmac_put(uri, timeout)
+        when :get
+          hmac_get(uri, timeout)
+        when :post
+          hmac_post(uri, timeout, request.body_parameters.to_json)
+        when :delete
+          hmac_delete(uri, timeout)
+        end
+      rescue Timeout::Error
+        fail ApiTimeout.new(@request)
+      end
+    end
+
+    private
+
+    def hmac_put(uri, timeout, options = {})
+      r = self.class.put(sign_url(uri), query: options, timeout: timeout)
+      check_errors r
+      r.body
+    end
+
+    def hmac_get(uri, timeout, options = {})
+      r = self.class.get(sign_url(uri), query: options, timeout: timeout)
+      check_errors r
+      JSON.parse(r.body)
+    end
+
+    def hmac_post(uri, timeout, options = {})
+      url = sign_url(uri)
+      # pass arguments in body
+      r = self.class.post(url, body: options, 
+                        headers: { 'Content-Type' => 'application/json' },
+                        timeout: timeout)
+      check_errors r
+      begin
+        return JSON.parse(r.body)
+      rescue JSON::ParserError
+        return r.body
+      end
+    end
+
+    def hmac_delete(uri, timeout, options = {})
+      r = self.class.delete(sign_url(uri), query: options, timeout: timeout)
+      check_errors r
+      r.body
+    end
+
+    def check_errors(response)
+      status_code = response.code
+      return if status_code == 200 || status_code == 201
+      fail ResponseError.new(@request, status_code, response.body)
+    end
+
+    # Sign request with HMAC, request URI must be exacly the same
+    # We have 30s to complete request with this token
+    def sign_url(req)
+      uri = "/#{@account}/#{req}"
+      time = hmac_time(uri)
+      sign = hmac_sign(uri, time)
+      @base_uri + uri + time + "&hmac_sign=#{sign}"
+    end
+
+    def hmac_time(uri)
+      res = (uri.include? '?') ? '&' : '?'
+      res << "hmac_timestamp=#{Time.now.utc.to_i}"
+    end
+
+    def hmac_sign(uri, time)
+      url = uri + time
+      Digest::HMAC.hexdigest(url, @token, Digest::SHA1)
+    end
+  end
+end