Release: v6.3.0

- Added support for property roles and metadata

Author: OndraFiedler

lib/recombee_api_client.rb

@@ -19,7 +19,7 @@ class RecombeeClient
     include HTTParty
 
     BATCH_MAX_SIZE = 10_000
-    USER_AGENT = { 'User-Agent' => 'recombee-ruby-api-client/6.2.0' }
+    USER_AGENT = { 'User-Agent' => 'recombee-ruby-api-client/6.3.0' }
 
     ##
     #   - +account+ -> Name of your account at Recombee

lib/recombee_api_client/api/add_item_property.rb

@@ -10,7 +10,7 @@ module RecombeeApiClient
   # Adding an item property is somewhat equivalent to adding a column to the table of items. The items may be characterized by various properties of different types.
   #
   class AddItemProperty < ApiRequest
-    attr_reader :property_name, :type
+    attr_reader :property_name, :type, :role, :metadata
     attr_accessor :timeout, :ensure_https
 
     ##
@@ -19,15 +19,15 @@ class AddItemProperty < ApiRequest
     #
     #   - +type+ -> Value type of the item property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`, `image` or `imageList`.
     #
-    # * `int`- Signed integer number.
+    # * `int` - Signed integer number.
     #
     # * `double` - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).
     #
     # * `string` - UTF-8 string.
     #
     # * `boolean` - *true* / *false*
     #
-    # * `timestamp` - Value representing date and time.
+    # * `timestamp` - Value representing date and time. ISO8601-1 pattern (string) or UTC epoch time (number).
     #
     # * `set` - Set of strings.
     #
@@ -36,11 +36,23 @@ class AddItemProperty < ApiRequest
     # * `imageList` - List of URLs that refer to images.
     #
     #
-    def initialize(property_name, type)
+    # * *Optional arguments (given as hash optional)*
+    #   - +role+ -> [Role](https://docs.recombee.com/api/property_roles_metadata#roles) to assign to the property.
+    #
+    #   - +metadata+ -> List of [metadata](https://docs.recombee.com/api/property_roles_metadata#metadata) entries to assign to the property.
+    #
+    def initialize(property_name, type, optional = {})
       @property_name = property_name
       @type = type
+      optional = normalize_hash_to_camel_case(optional)
+      @role = optional['role']
+      @metadata = optional['metadata']
+      @optional = optional
       @timeout = 100_000
       @ensure_https = false
+      @optional.each do |par, _|
+        raise UnknownOptionalParameter.new(par) unless %w[role metadata].include? par
+      end
     end
 
     # HTTP method
@@ -50,16 +62,18 @@ def method
 
     # Values of body parameters as a Hash
     def body_parameters
-      {}
+      p = {}
+      p['type'] = @type
+      p['role'] = @optional['role'] if @optional.include? 'role'
+      p['metadata'] = @optional['metadata'] if @optional.include? 'metadata'
+
+      p
     end
 
     # Values of query parameters as a Hash.
     # name of parameter => value of the parameter
     def query_parameters
-      params = {}
-      params['type'] = @type
-
-      params
+      {}
     end
 
     # Relative path to the endpoint

lib/recombee_api_client/api/add_user_property.rb

@@ -10,7 +10,7 @@ module RecombeeApiClient
   # Adding a user property is somewhat equivalent to adding a column to the table of users. The users may be characterized by various properties of different types.
   #
   class AddUserProperty < ApiRequest
-    attr_reader :property_name, :type
+    attr_reader :property_name, :type, :role, :metadata
     attr_accessor :timeout, :ensure_https
 
     ##
@@ -27,16 +27,28 @@ class AddUserProperty < ApiRequest
     #
     # * `boolean` - *true* / *false*
     #
-    # * `timestamp` - Value representing date and time.
+    # * `timestamp` - Value representing date and time. ISO8601-1 pattern (string) or UTC epoch time (number).
     #
     # * `set` - Set of strings.
     #
     #
-    def initialize(property_name, type)
+    # * *Optional arguments (given as hash optional)*
+    #   - +role+ -> [Role](https://docs.recombee.com/api/property_roles_metadata#roles) to assign to the property.
+    #
+    #   - +metadata+ -> List of [metadata](https://docs.recombee.com/api/property_roles_metadata#metadata) entries to assign to the property.
+    #
+    def initialize(property_name, type, optional = {})
       @property_name = property_name
       @type = type
+      optional = normalize_hash_to_camel_case(optional)
+      @role = optional['role']
+      @metadata = optional['metadata']
+      @optional = optional
       @timeout = 100_000
       @ensure_https = false
+      @optional.each do |par, _|
+        raise UnknownOptionalParameter.new(par) unless %w[role metadata].include? par
+      end
     end
 
     # HTTP method
@@ -46,16 +58,18 @@ def method
 
     # Values of body parameters as a Hash
     def body_parameters
-      {}
+      p = {}
+      p['type'] = @type
+      p['role'] = @optional['role'] if @optional.include? 'role'
+      p['metadata'] = @optional['metadata'] if @optional.include? 'metadata'
+
+      p
     end
 
     # Values of query parameters as a Hash.
     # name of parameter => value of the parameter
     def query_parameters
-      params = {}
-      params['type'] = @type
-
-      params
+      {}
     end
 
     # Relative path to the endpoint

lib/recombee_api_client/api/recommend_next_item_segments.rb

@@ -7,23 +7,24 @@ module RecombeeApiClient
   require_relative '../errors'
 
   ##
-  # Returns Item segments that shall be shown to a user as next recommendations when the user e.g. scrolls the page down (*infinite scroll*) or goes to the next page.
+  # Returns [Item Segments](https://docs.recombee.com/segmentations) to be shown as the next recommendations when a user scrolls (e.g., within a carousel or feed of Item Segments such as brands, artists, topics, or categories).
+  #
+  # The request requires the `recommId` of a base recommendation request and the number of Segments to return (`count`).
   #
-  # It accepts `recommId` of a base recommendation request (e.g., request from the first page) and the number of segments that shall be returned (`count`).
   # The base request can be one of:
   #  - [Recommend Item Segments to Item](https://docs.recombee.com/api#recommend-item-segments-to-item)
   #  - [Recommend Item Segments to User](https://docs.recombee.com/api#recommend-item-segments-to-user)
   #  - [Recommend Item Segments to Item Segment](https://docs.recombee.com/api#recommend-item-segments-to-item-segment)
   #  - [Search Item Segments](https://docs.recombee.com/api#search-item-segments)
   #
-  # All the other parameters are inherited from the base request.
+  # All other parameters are inherited from the base request associated with the provided `recommId`.
   #
-  # *Recommend next Item segments* can be called many times for a single `recommId` and each call returns different (previously not recommended) segments.
-  # The number of *Recommend next Item segments* calls performed so far is returned in the `numberNextRecommsCalls` field.
+  # This endpoint can be called multiple times for a single `recommId`. Each call returns different Item Segments that have not been recommended in previous calls.
+  # The number of calls made so far is returned in the `numberNextRecommsCalls` field.
   #
-  # *Recommend next Item segments* can be requested up to 30 minutes after the base request or a previous *Recommend next Item segments* call.
+  # Requests can be made up to 30 minutes after the base request or the most recent Recommend Next Item Segments call.
   #
-  # For billing purposes, each call to *Recommend next Item segments* is counted as a separate recommendation request.
+  # For billing purposes, each call to this endpoint is counted as a separate recommendation request.
   #
   class RecommendNextItemSegments < ApiRequest
     attr_reader :recomm_id, :count

lib/recombee_api_client/inputs/property_metadata.rb

@@ -0,0 +1,46 @@
+#
+# This file is auto-generated, do not edit
+#
+
+require 'json'
+
+module RecombeeApiClient
+  require_relative 'input'
+  require_relative '../errors'
+
+  ##
+  # Initializes PropertyMetadata input#
+  class PropertyMetadata < Input
+    attr_reader :name, :settings
+
+    ##
+    # * *Required arguments*
+    #   - +name+ -> Name of the [metadata](https://docs.recombee.com/api/property_roles_metadata#metadata) assigned to the property.
+    #
+    # * *Optional arguments (given as hash optional)*
+    #   - +settings+ -> Optional configuration for this metadata entry.
+    #
+    def initialize(name, optional = {})
+      @name = name
+      optional = normalize_hash_to_camel_case(optional)
+      @settings = optional['settings']
+      @optional = optional
+      @optional.each do |par, _|
+        raise UnknownOptionalParameter.new(par) unless ['settings'].include? par
+      end
+    end
+
+    # Return only JSON-serializable primitives.
+    def as_json(_options = {})
+      res = {}
+      res['name'] = @name
+      res['settings'] = @optional['settings'] if @optional['settings']
+
+      res
+    end
+
+    def to_json(*args)
+      as_json.to_json(*args)
+    end
+  end
+end

lib/recombee_api_client/inputs/property_role.rb

@@ -0,0 +1,46 @@
+#
+# This file is auto-generated, do not edit
+#
+
+require 'json'
+
+module RecombeeApiClient
+  require_relative 'input'
+  require_relative '../errors'
+
+  ##
+  # Initializes PropertyRole input#
+  class PropertyRole < Input
+    attr_reader :name, :settings
+
+    ##
+    # * *Required arguments*
+    #   - +name+ -> Name of the [role](https://docs.recombee.com/api/property_roles_metadata#roles) assigned to the property.
+    #
+    # * *Optional arguments (given as hash optional)*
+    #   - +settings+ -> Optional configuration specific to the selected role.
+    #
+    def initialize(name, optional = {})
+      @name = name
+      optional = normalize_hash_to_camel_case(optional)
+      @settings = optional['settings']
+      @optional = optional
+      @optional.each do |par, _|
+        raise UnknownOptionalParameter.new(par) unless ['settings'].include? par
+      end
+    end
+
+    # Return only JSON-serializable primitives.
+    def as_json(_options = {})
+      res = {}
+      res['name'] = @name
+      res['settings'] = @optional['settings'] if @optional['settings']
+
+      res
+    end
+
+    def to_json(*args)
+      as_json.to_json(*args)
+    end
+  end
+end

lib/recombee_api_client/version.rb

@@ -1,3 +1,3 @@
 module RecombeeApiClient
-  VERSION = '6.2.0'
+  VERSION = '6.3.0'
 end

spec/api/add_item_property.rb

@@ -0,0 +1,52 @@
+#
+# This file is auto-generated, do not edit
+#
+
+require 'spec_helper'
+require_relative 'set_environment'
+shared_examples 'add item property' do
+  include_context 'set environment'
+
+  it 'does not fail with valid name and type' do
+    req = described_class.new('number', 'int')
+    @client.send(req)
+    req = described_class.new('str', 'string')
+    @client.send(req)
+  end
+
+  it 'fails with invalid type' do
+    req = described_class.new('prop', 'integer')
+    expect { @client.send(req) }.to(raise_exception do |exception|
+      expect(exception).to be_a(RecombeeApiClient::ResponseError)
+      expect(exception.status_code).to eq 400
+    end)
+  end
+
+  it 'really stores property to the system' do
+    req = described_class.new('number2', 'int')
+    @client.send(req)
+    expect { @client.send(req) }.to(raise_exception do |exception|
+      expect(exception).to be_a(RecombeeApiClient::ResponseError)
+      expect(exception.status_code).to eq 409
+    end)
+  end
+
+  it 'does not fail with valid property role and metadata' do
+    req = described_class.new('title', 'string', { 'role' => 'title' })
+    @client.send(req)
+  end
+
+  it 'fails with duplicate property role or invalid metadata' do
+    req = described_class.new('str4', 'string', { 'role' => 'summary' })
+    @client.send(req)
+    expect { @client.send(req) }.to(raise_exception do |exception|
+      expect(exception).to be_a(RecombeeApiClient::ResponseError)
+      expect(exception.status_code).to eq 409
+    end)
+    req = described_class.new('str5', 'string', { 'role' => 'titl' })
+    expect { @client.send(req) }.to(raise_exception do |exception|
+      expect(exception).to be_a(RecombeeApiClient::ResponseError)
+      expect(exception.status_code).to eq 404
+    end)
+  end
+end

spec/api/add_item_property_spec.rb

@@ -3,8 +3,8 @@
 #
 
 require 'spec_helper'
-require_relative 'add_property'
+require_relative 'add_item_property'
 
 describe RecombeeApiClient::AddItemProperty do
-  it_behaves_like 'add property'
+  it_behaves_like 'add item property'
 end

spec/api/add_property.rb spec/api/add_user_property.rbspec/api/add_property.rb renamed to spec/api/add_user_property.rb

@@ -4,7 +4,7 @@
 
 require 'spec_helper'
 require_relative 'set_environment'
-shared_examples 'add property' do
+shared_examples 'add user property' do
   include_context 'set environment'
 
   it 'does not fail with valid name and type' do