recombee_api_client 2.2.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 891734600f45e2e25c9a44617f0e2ce033b6e90c
-  data.tar.gz: 6aca79bfa8720f2187f14ec117a60b02a4e18995
+SHA256:
+  metadata.gz: 993911797068c239b3eb1ed0bff4f115049a3a7c5c25cc10ee2e7606fabaecc5
+  data.tar.gz: 9759c4ad279ea317cbdf0d6b3ac93eee89761010b1d8aded8cdd946f9dc0e793
 SHA512:
-  metadata.gz: bc1533bd22417f9ddb1fae6ce533e623854d425b966a72d98f2d994796c3aa909e73ef1a3a5cebb92cabd2397f2e7477f2c09765b8e1dfa498a0e9256da9cd73
-  data.tar.gz: 5a8c325f7bce984ac02e397d9a16dfd21b132178ec836e7dddd509f7ef242c86cc61dc7b5fdabe06239f36e0813682e102d3cd92279e88dd8bd8fb6424799cea
+  metadata.gz: 7a5cccd32d72f4ec654b3ffc9c8f9d0f50e90618b104afc7618e24cf40f0ad9ceaf14b18031d7e8c4ef1ac05027a7857a592e3fc18fded5a7a2f1b27b80f9225
+  data.tar.gz: 8a68e11edd23890854ec6248994d77e4f494fd19b881d798eb7f916b0823b77987695ad0c439594fdadc82c7f229cda3128ce6d3dfecdd17162e38654d1f3200

data/README.md

@@ -29,7 +29,7 @@ Or install it yourself as:
 require 'recombee_api_client'
 include RecombeeApiClient
 
-client = RecombeeClient('--my-database-id--', '--my-secret-token--')
+client = RecombeeClient('--my-database-id--', '--db-private-token--')
 
 # Generate some random purchases of items by users
 NUM = 100
@@ -55,8 +55,13 @@ begin
   client.send(Batch.new(purchases))
   
   # Get recommendations for user 'user-25'
-  recommended = client.send(RecommendItemsToUser.new('user-25', 5))
-  puts "Recommended items for user-25: #{recommended}"
+  response = client.send(RecommendItemsToUser.new('user-25', 5))
+  puts "Recommended items for user-25: #{response}"
+
+  # User scrolled down - get next 3 recommended items
+  response = client.send(RecommendNextItems.new(response['recommId'], 3))
+  puts "Next recommended items for user-25: #{response}"
+
 rescue APIError => e
   puts e
   # Use fallback
@@ -71,8 +76,8 @@ include RecombeeApiClient
 NUM = 100
 PROBABILITY_PURCHASED = 0.1
 
-client = RecombeeClient('--my-database-id--', '--my-secret-token--')
-client.send(ResetDatabase.new) # Clear everything from the database
+client = RecombeeClient('--my-database-id--', '--db-private-token--')
+client.send(ResetDatabase.new) # Clear everything from the database (asynchronous)
 
 # We will use computers as items in this example
 # Computers have five properties 
@@ -103,7 +108,7 @@ requests = (1..NUM).map do |i|
       },
       #optional parameters:
       {
-        'cascadeCreate' => true  # Use cascadeCreate for creating item
+        :cascade_create => true  # Use cascade_create for creating item
                                  # with given itemId, if it doesn't exist
       }
     )
@@ -117,29 +122,38 @@ requests = []
 (1..NUM).map{|i| "computer-#{i}"}.each do |item_id|
   user_ids = (1..NUM).map{|i| "user-#{i}"}
   user_ids = user_ids.select { |_| rand(0.0..1.0) < PROBABILITY_PURCHASED }
-  # Use cascadeCreate to create unexisting users
-  user_ids.each { |user_id| requests.push(AddPurchase.new(user_id, item_id, 'cascadeCreate' => true)) }
+  # Use cascade_create to create unexisting users
+  user_ids.each { |user_id| requests.push(AddPurchase.new(user_id, item_id, :cascade_create => true)) }
 end
 
 # Send purchases to the recommender system
 client.send(Batch.new(requests))
 
 # Get 5 recommendations for user-42, who is currently viewing computer-6
-recommended = client.send(RecommendItemsToItem.new('computer-6', 'user-42', 5) )
-puts "Recommended items: #{recommended}"
-
 # Recommend only computers that have at least 3 cores
 recommended = client.send(
-  RecommendItemsToItem.new('computer-6', 'user-42', 5, {'filter' => "'num-cores'>=3"})
+  RecommendItemsToItem.new('computer-6', 'user-42', 5, {:filter => "'num-cores'>=3"})
   )
 puts "Recommended items with at least 3 processor cores: #{recommended}"
 
-# Recommend only items thatare more expensive then currently viewed item (up-sell)
+# Recommend only items that are more expensive then currently viewed item (up-sell)
 recommended = client.send(
   RecommendItemsToItem.new('computer-6', 'user-42', 5,
-    {'filter' => "'price' > context_item[\"price\"]"})
+    {:filter => "'price' > context_item[\"price\"]"})
   )
 puts "Recommended up-sell items: #{recommended}"
+
+# Filters, boosters and other settings can be also set in the Admin UI (admin.recombee.com)
+# when scenario is specified
+recommended = client.send(
+  RecommendItemsToItem.new('computer-6', 'user-42', 5, {:scenario => 'product_detail'})
+  )
+
+# Perform personalized full-text search with a user's search query (e.g. 'computers').
+matches = client.send(
+  SearchItems.new('user-42', 'computers', 5, {:scenario => 'search_top'})
+  )
+puts "Matched items: #{matches}"
 ```
 
 ### Exception handling

data/lib/recombee_api_client.rb

@@ -18,13 +18,13 @@ module RecombeeApiClient
     include HTTParty
 
     BATCH_MAX_SIZE = 10000
-    USER_AGENT = {'User-Agent' => 'recombee-ruby-api-client/2.2.0'}
+    USER_AGENT = {'User-Agent' => 'recombee-ruby-api-client/3.2.0'}
 
     ##
     #   - +account+ -> Name of your account at Recombee
     #   - +token+ -> Secret token obtained from Recombee for signing requests
     #   - +protocol+ -> Default protocol for sending requests. Possible values: 'http', 'https'.
-    def initialize(account, token, protocol = 'http', options = {})
+    def initialize(account, token, protocol = 'https', options = {})
       @account = account
       @token = token
       @protocol = protocol

data/lib/recombee_api_client/api/add_bookmark.rb

@@ -10,7 +10,7 @@ module RecombeeApiClient
   #Adds a bookmark of a given item made by a given user.
   #
   class AddBookmark < ApiRequest
-    attr_reader :user_id, :item_id, :timestamp, :cascade_create, :recomm_id
+    attr_reader :user_id, :item_id, :timestamp, :cascade_create, :recomm_id, :additional_data
     attr_accessor :timeout
     attr_accessor :ensure_https
   
@@ -23,6 +23,7 @@ module RecombeeApiClient
   #   - +timestamp+ -> UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
   #   - +cascadeCreate+ -> Sets whether the given user/item should be created if not present in the database.
   #   - +recommId+ -> If this bookmark is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+  #   - +additionalData+ -> A dictionary of additional data for the interaction.
   #
     def initialize(user_id, item_id, optional = {})
       @user_id = user_id
@@ -31,11 +32,12 @@ module RecombeeApiClient
       @timestamp = optional['timestamp']
       @cascade_create = optional['cascadeCreate']
       @recomm_id = optional['recommId']
+      @additional_data = optional['additionalData']
       @optional = optional
       @timeout = 1000
       @ensure_https = false
       @optional.each do |par, _|
-        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","recommId"].include? par
+        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","recommId","additionalData"].include? par
       end
     end
   
@@ -52,6 +54,7 @@ module RecombeeApiClient
       p['timestamp'] = @optional['timestamp'] if @optional.include? 'timestamp'
       p['cascadeCreate'] = @optional['cascadeCreate'] if @optional.include? 'cascadeCreate'
       p['recommId'] = @optional['recommId'] if @optional.include? 'recommId'
+      p['additionalData'] = @optional['additionalData'] if @optional.include? 'additionalData'
       p
     end
   

data/lib/recombee_api_client/api/add_cart_addition.rb

@@ -10,7 +10,7 @@ module RecombeeApiClient
   #Adds a cart addition of a given item made by a given user.
   #
   class AddCartAddition < ApiRequest
-    attr_reader :user_id, :item_id, :timestamp, :cascade_create, :amount, :price, :recomm_id
+    attr_reader :user_id, :item_id, :timestamp, :cascade_create, :amount, :price, :recomm_id, :additional_data
     attr_accessor :timeout
     attr_accessor :ensure_https
   
@@ -25,6 +25,7 @@ module RecombeeApiClient
   #   - +amount+ -> Amount (number) added to cart. The default is 1. For example if `user-x` adds two `item-y` during a single order (session...), the `amount` should equal to 2.
   #   - +price+ -> Price of the added item. If `amount` is greater than 1, sum of prices of all the items should be given.
   #   - +recommId+ -> If this cart addition is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+  #   - +additionalData+ -> A dictionary of additional data for the interaction.
   #
     def initialize(user_id, item_id, optional = {})
       @user_id = user_id
@@ -35,11 +36,12 @@ module RecombeeApiClient
       @amount = optional['amount']
       @price = optional['price']
       @recomm_id = optional['recommId']
+      @additional_data = optional['additionalData']
       @optional = optional
       @timeout = 1000
       @ensure_https = false
       @optional.each do |par, _|
-        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","amount","price","recommId"].include? par
+        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","amount","price","recommId","additionalData"].include? par
       end
     end
   
@@ -58,6 +60,7 @@ module RecombeeApiClient
       p['amount'] = @optional['amount'] if @optional.include? 'amount'
       p['price'] = @optional['price'] if @optional.include? 'price'
       p['recommId'] = @optional['recommId'] if @optional.include? 'recommId'
+      p['additionalData'] = @optional['additionalData'] if @optional.include? 'additionalData'
       p
     end
   

data/lib/recombee_api_client/api/add_detail_view.rb

@@ -10,7 +10,7 @@ module RecombeeApiClient
   #Adds a detail view of a given item made by a given user.
   #
   class AddDetailView < ApiRequest
-    attr_reader :user_id, :item_id, :timestamp, :duration, :cascade_create, :recomm_id
+    attr_reader :user_id, :item_id, :timestamp, :duration, :cascade_create, :recomm_id, :additional_data
     attr_accessor :timeout
     attr_accessor :ensure_https
   
@@ -24,6 +24,7 @@ module RecombeeApiClient
   #   - +duration+ -> Duration of the view
   #   - +cascadeCreate+ -> Sets whether the given user/item should be created if not present in the database.
   #   - +recommId+ -> If this detail view is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+  #   - +additionalData+ -> A dictionary of additional data for the interaction.
   #
     def initialize(user_id, item_id, optional = {})
       @user_id = user_id
@@ -33,11 +34,12 @@ module RecombeeApiClient
       @duration = optional['duration']
       @cascade_create = optional['cascadeCreate']
       @recomm_id = optional['recommId']
+      @additional_data = optional['additionalData']
       @optional = optional
       @timeout = 1000
       @ensure_https = false
       @optional.each do |par, _|
-        fail UnknownOptionalParameter.new(par) unless ["timestamp","duration","cascadeCreate","recommId"].include? par
+        fail UnknownOptionalParameter.new(par) unless ["timestamp","duration","cascadeCreate","recommId","additionalData"].include? par
       end
     end
   
@@ -55,6 +57,7 @@ module RecombeeApiClient
       p['duration'] = @optional['duration'] if @optional.include? 'duration'
       p['cascadeCreate'] = @optional['cascadeCreate'] if @optional.include? 'cascadeCreate'
       p['recommId'] = @optional['recommId'] if @optional.include? 'recommId'
+      p['additionalData'] = @optional['additionalData'] if @optional.include? 'additionalData'
       p
     end
   

data/lib/recombee_api_client/api/add_purchase.rb

@@ -10,7 +10,7 @@ module RecombeeApiClient
   #Adds a purchase of a given item made by a given user.
   #
   class AddPurchase < ApiRequest
-    attr_reader :user_id, :item_id, :timestamp, :cascade_create, :amount, :price, :profit, :recomm_id
+    attr_reader :user_id, :item_id, :timestamp, :cascade_create, :amount, :price, :profit, :recomm_id, :additional_data
     attr_accessor :timeout
     attr_accessor :ensure_https
   
@@ -26,6 +26,7 @@ module RecombeeApiClient
   #   - +price+ -> Price paid by the user for the item. If `amount` is greater than 1, sum of prices of all the items should be given.
   #   - +profit+ -> Your profit from the purchased item. The profit is natural in e-commerce domain (for example if `user-x` purchases `item-y` for $100 and the gross margin is 30 %, then the profit is $30), but is applicable also in other domains (for example at a news company it may be income from displayed advertisement on article page). If `amount` is greater than 1, sum of profit of all the items should be given.
   #   - +recommId+ -> If this purchase is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+  #   - +additionalData+ -> A dictionary of additional data for the interaction.
   #
     def initialize(user_id, item_id, optional = {})
       @user_id = user_id
@@ -37,11 +38,12 @@ module RecombeeApiClient
       @price = optional['price']
       @profit = optional['profit']
       @recomm_id = optional['recommId']
+      @additional_data = optional['additionalData']
       @optional = optional
       @timeout = 1000
       @ensure_https = false
       @optional.each do |par, _|
-        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","amount","price","profit","recommId"].include? par
+        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","amount","price","profit","recommId","additionalData"].include? par
       end
     end
   
@@ -61,6 +63,7 @@ module RecombeeApiClient
       p['price'] = @optional['price'] if @optional.include? 'price'
       p['profit'] = @optional['profit'] if @optional.include? 'profit'
       p['recommId'] = @optional['recommId'] if @optional.include? 'recommId'
+      p['additionalData'] = @optional['additionalData'] if @optional.include? 'additionalData'
       p
     end
   

data/lib/recombee_api_client/api/add_rating.rb

@@ -10,7 +10,7 @@ module RecombeeApiClient
   #Adds a rating of given item made by a given user.
   #
   class AddRating < ApiRequest
-    attr_reader :user_id, :item_id, :timestamp, :rating, :cascade_create, :recomm_id
+    attr_reader :user_id, :item_id, :timestamp, :rating, :cascade_create, :recomm_id, :additional_data
     attr_accessor :timeout
     attr_accessor :ensure_https
   
@@ -24,6 +24,7 @@ module RecombeeApiClient
   #   - +timestamp+ -> UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
   #   - +cascadeCreate+ -> Sets whether the given user/item should be created if not present in the database.
   #   - +recommId+ -> If this rating is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+  #   - +additionalData+ -> A dictionary of additional data for the interaction.
   #
     def initialize(user_id, item_id, rating, optional = {})
       @user_id = user_id
@@ -33,11 +34,12 @@ module RecombeeApiClient
       @timestamp = optional['timestamp']
       @cascade_create = optional['cascadeCreate']
       @recomm_id = optional['recommId']
+      @additional_data = optional['additionalData']
       @optional = optional
       @timeout = 1000
       @ensure_https = false
       @optional.each do |par, _|
-        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","recommId"].include? par
+        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","recommId","additionalData"].include? par
       end
     end
   
@@ -55,6 +57,7 @@ module RecombeeApiClient
       p['timestamp'] = @optional['timestamp'] if @optional.include? 'timestamp'
       p['cascadeCreate'] = @optional['cascadeCreate'] if @optional.include? 'cascadeCreate'
       p['recommId'] = @optional['recommId'] if @optional.include? 'recommId'
+      p['additionalData'] = @optional['additionalData'] if @optional.include? 'additionalData'
       p
     end
   

data/lib/recombee_api_client/api/add_search_synonym.rb

@@ -0,0 +1,72 @@
+#
+# This file is auto-generated, do not edit
+#
+
+module RecombeeApiClient
+  require_relative 'request'
+  require_relative '../errors'
+  
+  ##
+  #Adds a new synonym for the [Search items](https://docs.recombee.com/api.html#search-items).
+  #
+  #When the `term` is used in the search query, the `synonym` is also used for the full-text search.
+  #Unless `oneWay=true`, it works also in the opposite way (`synonym` -> `term`).
+  #
+  #An example of a synonym can be `science fiction` for the term `sci-fi`.
+  #
+  class AddSearchSynonym < ApiRequest
+    attr_reader :term, :synonym, :one_way
+    attr_accessor :timeout
+    attr_accessor :ensure_https
+  
+  ##
+  # * *Required arguments*
+  #   - +term+ -> A word to which the `synonym` is specified.
+  #   - +synonym+ -> A word that should be considered equal to the `term` by the full-text search engine.
+  #
+  # * *Optional arguments (given as hash optional)*
+  #   - +oneWay+ -> If set to `true`, only `term` -> `synonym` is considered. If set to `false`, also `synonym` -> `term` works.
+  #
+  #Default: `false`.
+  #
+  #
+    def initialize(term, synonym, optional = {})
+      @term = term
+      @synonym = synonym
+      optional = normalize_optional(optional)
+      @one_way = optional['oneWay']
+      @optional = optional
+      @timeout = 10000
+      @ensure_https = false
+      @optional.each do |par, _|
+        fail UnknownOptionalParameter.new(par) unless ["oneWay"].include? par
+      end
+    end
+  
+    # HTTP method
+    def method
+      :post
+    end
+  
+    # Values of body parameters as a Hash
+    def body_parameters
+      p = Hash.new
+      p['term'] = @term
+      p['synonym'] = @synonym
+      p['oneWay'] = @optional['oneWay'] if @optional.include? 'oneWay'
+      p
+    end
+  
+    # Values of query parameters as a Hash.
+    # name of parameter => value of the parameter
+    def query_parameters
+      params = {}
+      params
+    end
+  
+    # Relative path to the endpoint
+    def path
+      "/{databaseId}/synonyms/items/"
+    end
+  end
+end

data/lib/recombee_api_client/api/delete_all_search_synonyms.rb

@@ -0,0 +1,47 @@
+#
+# This file is auto-generated, do not edit
+#
+
+module RecombeeApiClient
+  require_relative 'request'
+  require_relative '../errors'
+  
+  ##
+  #Deletes all synonyms defined in the database.
+  #
+  class DeleteAllSearchSynonyms < ApiRequest
+  
+    attr_accessor :timeout
+    attr_accessor :ensure_https
+  
+  ##
+  #
+    def initialize()
+      @timeout = 10000
+      @ensure_https = false
+    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 parameters as a Hash.
+    # name of parameter => value of the parameter
+    def query_parameters
+      params = {}
+      params
+    end
+  
+    # Relative path to the endpoint
+    def path
+      "/{databaseId}/synonyms/items/"
+    end
+  end
+end

data/lib/recombee_api_client/api/delete_search_synonym.rb

@@ -0,0 +1,50 @@
+#
+# This file is auto-generated, do not edit
+#
+
+module RecombeeApiClient
+  require_relative 'request'
+  require_relative '../errors'
+  
+  ##
+  #Deletes synonym of given `id` and this synonym is no longer taken into account in the [Search items](https://docs.recombee.com/api.html#search-items).
+  #
+  class DeleteSearchSynonym < ApiRequest
+    attr_reader :id
+    attr_accessor :timeout
+    attr_accessor :ensure_https
+  
+  ##
+  # * *Required arguments*
+  #   - +id+ -> ID of the synonym that should be deleted.
+  #
+    def initialize(id)
+      @id = id
+      @timeout = 10000
+      @ensure_https = false
+    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 parameters as a Hash.
+    # name of parameter => value of the parameter
+    def query_parameters
+      params = {}
+      params
+    end
+  
+    # Relative path to the endpoint
+    def path
+      "/{databaseId}/synonyms/items/#{@id}"
+    end
+  end
+end