rosette_api 1.14.4 → 1.37.0

data/lib/name_similarity_parameters.rb

@@ -4,26 +4,28 @@ require_relative 'bad_request_error'
 require_relative 'name_parameter'
 
 # This class encapsulates parameters that are needed for name-similarity in
-# Rosette API.
+# Analytics API.
 class NameSimilarityParameters
   # genre to categorize the input data
   attr_accessor :genre
+  # Deprecated: Retained for backward compatibility. Use 'parameters' instead.
   # Rosette API options (optional, should be a hash)
   attr_accessor :rosette_options
+  # Parameters map sent to the API (optional, should be a hash)
+  attr_accessor :parameters
   # Name to be compared to name2
   attr_accessor :name1
   # Name to be compared to name1
   attr_accessor :name2
 
-  def initialize(name1, name2, options = {}) #:notnew:
-    options = {
-      genre: nil,
-      rosette_options: nil
-    }.update options
-    @genre = options[:genre]
+  def initialize(name1, name2, match_parameters = nil) # :notnew:
     @name1 = name1
     @name2 = name2
-    @rosette_options = options[:rosette_options]
+    @genre = nil
+    @parameters = nil
+    @rosette_options = nil
+
+    handle_match_parameters(match_parameters) if match_parameters
   end
 
   # Validates the parameters by checking if name1 and name2 are instances of
@@ -35,10 +37,11 @@ class NameSimilarityParameters
     n2_msg = 'name2 option can only be an instance of a String or NameParameter'
     raise BadRequestError.new(n2_msg) if [String, NameParameter].none? { |clazz| @name2.is_a? clazz }
 
-    opt_msg = 'rosette_options can only be an instance of a Hash'
-    if @rosette_options
-      raise BadRequestError.new(opt_msg) unless @rosette_options.is_a? Hash
-    end
+    opt_msg = 'parameters can only be an instance of a Hash'
+    raise BadRequestError.new(opt_msg) if @parameters && !(@parameters.is_a? Hash)
+
+    rosette_opt_msg = 'rosette_options can only be an instance of a Hash'
+    raise BadRequestError.new(rosette_opt_msg) if @rosette_options && !(@rosette_options.is_a? Hash)
   end
 
   # Converts this class to Hash with its keys in lower CamelCase.
@@ -47,20 +50,47 @@ class NameSimilarityParameters
   def load_params
     validate_params
     to_hash
-      .reject { |_key, value| value.nil? }
-      .map { |key, value| [key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase), value] }
-      .to_h
+      .compact
+      .transform_keys { |key| key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase) }
   end
 
   # Converts this class to Hash.
   #
   # Returns the new Hash.
   def to_hash
-    {
-      genre: @genre,
-      name1: @name1.is_a?(NameParameter) ? @name1.load_param : @name1,
-      name2: @name2.is_a?(NameParameter) ? @name2.load_param : @name2,
-      options: @rosette_options
-    }
+    if @parameters
+      {
+        name1: @name1.is_a?(NameParameter) ? @name1.load_param : @name1,
+        name2: @name2.is_a?(NameParameter) ? @name2.load_param : @name2,
+        parameters: @parameters
+      }
+    else
+      {
+        genre: @genre,
+        name1: @name1.is_a?(NameParameter) ? @name1.load_param : @name1,
+        name2: @name2.is_a?(NameParameter) ? @name2.load_param : @name2,
+        options: @rosette_options
+      }
+    end
+  end
+
+  private
+
+  # Processes the 3rd argument to determine if it is using the legacy 'options' signature
+  # or the new 'match_parameters' signature, and assigns instance variables accordingly.
+  def handle_match_parameters(match_parameters)
+    if legacy_options?(match_parameters)
+      warn 'DEPRECATION WARNING: Passing `options` dynamically via NameSimilarityParameters.new is deprecated. Please pass `parameters` instead.'
+      @genre = match_parameters[:genre] || match_parameters['genre']
+      @rosette_options = match_parameters[:rosette_options] || match_parameters['rosette_options']
+    else
+      @parameters = match_parameters
+    end
+  end
+
+  def legacy_options?(params)
+    return false unless params.is_a?(Hash)
+
+    params.key?(:genre) || params.key?('genre') || params.key?(:rosette_options) || params.key?('rosette_options')
   end
 end

data/lib/name_translation_parameters.rb

@@ -3,7 +3,7 @@
 require_relative 'rosette_api_error'
 
 # This class encapsulates parameters that are needed for name-translation in
-# Rosette API.
+# Analytics API.
 class NameTranslationParameters
   # Name's entity type (PERSON, LOCATION, ORGANIZATION) (optional)
   attr_accessor :entity_type
@@ -11,7 +11,7 @@ class NameTranslationParameters
   attr_accessor :genre
   # Name to translate
   attr_accessor :name
-  # Rosette API options (optional, should be a hash)
+  # API options (optional, should be a hash)
   attr_accessor :rosette_options
   # ISO 693-3 code of the name's native language the name originates in
   # (optional)
@@ -26,11 +26,14 @@ class NameTranslationParameters
   attr_accessor :target_scheme
   # ISO 15924 code of name's script (optional)
   attr_accessor :target_script
+  # Maximum number of results to return (optional)
+  attr_accessor :maximum_results
 
-  def initialize(name, target_language, options = {}) #:notnew:
+  def initialize(name, target_language, options = {}) # :notnew:
     options = {
       entity_type: nil,
       genre: nil,
+      maximum_results: nil,
       rosette_options: nil,
       source_language_of_origin: nil,
       source_language_of_use: nil,
@@ -41,6 +44,7 @@ class NameTranslationParameters
     @name = name
     @entity_type = options[:entity_type]
     @genre = options[:genre]
+    @maximum_results = options[:maximum_results]
     @rosette_options = options[:rosette_options]
     @source_language_of_origin = options[:source_language_of_origin]
     @source_language_of_use = options[:source_language_of_use]
@@ -54,9 +58,13 @@ class NameTranslationParameters
   # of a Hash.
   def validate_params
     msg = 'rosette_options can only be an instance of a Hash'
-    if @rosette_options
-      raise BadRequestError.new(msg) unless @rosette_options.is_a? Hash
-    end
+    raise BadRequestError.new(msg) if @rosette_options && !(@rosette_options.is_a? Hash)
+
+    max_msg = 'maximum_results can only be an instance of an Integer'
+    raise BadRequestError.new(max_msg) if @maximum_results && !(@maximum_results.is_a? Integer)
+
+    max_range_msg = 'maximum_results must be greater than or equal to 0'
+    raise BadRequestError.new(max_range_msg) if @maximum_results&.negative?
   end
 
   # Converts this class to Hash with its keys in lower CamelCase.
@@ -66,8 +74,7 @@ class NameTranslationParameters
     validate_params
     to_hash
       .select { |_key, value| value }
-      .map { |key, value| [key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase), value] }
-      .to_h
+      .transform_keys { |key| key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase) }
   end
 
   # Converts this class to Hash.
@@ -76,7 +83,6 @@ class NameTranslationParameters
   def to_hash
     {
       entity_type: @entity_type,
-      genre: @genre,
       name: @name,
       options: @rosette_options,
       source_language_of_origin: @source_language_of_origin,
@@ -84,7 +90,8 @@ class NameTranslationParameters
       source_script: @source_script,
       target_language: @target_language,
       target_scheme: @target_scheme,
-      target_script: @target_script
+      target_script: @target_script,
+      maximum_results: @maximum_results
     }
   end
 end

data/lib/record_similarity_parameters.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative 'bad_request_error'
+
+# This class encapsulates parameters that are needed for record-similarity in
+# Analytics API.
+class RecordSimilarityParameters
+  # Records to be compared (required)
+  attr_accessor :records
+
+  # Field names/definitions used for similarity scoring (required)
+  attr_accessor :fields
+
+  # Optional properties map sent to the API (optional, should be a hash)
+  attr_accessor :properties
+
+  def initialize(fields, records, properties = nil) # :notnew:
+    @fields = fields
+    @records = records
+    @properties = properties
+  end
+
+  # Validates the parameters by checking if required fields are present and
+  # optional properties is a Hash if provided.
+  def validate_params
+    f_msg = 'fields option is required'
+    raise BadRequestError.new(f_msg) if @fields.nil?
+
+    f_type_msg = 'fields can only be an instance of a Hash'
+    raise BadRequestError.new(f_type_msg) unless @fields.is_a? Hash
+
+    f_empty_msg = 'fields must not be empty'
+    raise BadRequestError.new(f_empty_msg) if @fields.empty?
+
+    r_msg = 'records option is required'
+    raise BadRequestError.new(r_msg) if @records.nil?
+
+    r_type_msg = 'records can only be an instance of a Hash'
+    raise BadRequestError.new(r_type_msg) unless @records.is_a? Hash
+
+    r_empty_msg = 'records must not be empty'
+    raise BadRequestError.new(r_empty_msg) if @records.empty?
+
+    p_msg = 'properties can only be an instance of a Hash'
+    raise BadRequestError.new(p_msg) if @properties && !(@properties.is_a? Hash)
+  end
+
+  # Converts this class to Hash with its keys in lower CamelCase.
+  #
+  # Returns the new Hash.
+  def load_params
+    validate_params
+    to_hash
+      .compact
+      .transform_keys { |key| key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase) }
+  end
+
+  # Converts this class to Hash.
+  #
+  # Returns the new Hash.
+  def to_hash
+    {
+      fields: @fields,
+      records: @records,
+      properties: @properties
+    }
+  end
+end

data/lib/request_builder.rb

@@ -6,17 +6,45 @@ require 'json'
 require 'securerandom'
 require_relative 'rosette_api_error'
 
-# This class handles all Rosette API requests.
+# This class handles all Analytics API requests.
 class RequestBuilder
-  # Alternate Rosette API URL
+  CONNECTION_ERROR_CODE = 'connectionError'
+  CONNECTION_ERROR_MESSAGE = 'Failed to establish connection with Analytics server.'
+
+  INVALID_HEADER_CODE = 'invalidHeader'
+  INVALID_HEADER_MESSAGE = 'Custom header must begin with "X-RosetteAPI-" or "X-BabelStreetAPI-"'
+
+  READ_MULTIPART_ERROR_CODE = 'readMultipartError'
+
+  HEADER_API_KEY = 'X-BabelStreetAPI-Key'
+  HEADER_CONTENT_TYPE = 'Content-Type'
+  HEADER_ACCEPT = 'Accept'
+  HEADER_USER_AGENT = 'User-Agent'
+  HEADER_BINDING_LEGACY = 'X-RosetteAPI-Binding'
+  HEADER_BINDING = 'X-BabelStreetAPI-Binding'
+  HEADER_BINDING_VERSION_LEGACY = 'X-RosetteAPI-Binding-Version'
+  HEADER_BINDING_VERSION = 'X-BabelStreetAPI-Binding-Version'
+
+  BINDING_NAME = 'ruby'
+
+  CONTENT_TYPE_JSON = 'application/json'
+  CONTENT_TYPE_TEXT_PLAIN = 'text/plain'
+  ACCEPT_JSON = 'application/json'
+
+  MULTIPART_FORM_DATA = 'multipart/form-data'
+
+  CUSTOM_HEADER_PREFIX_ROSETTE = /^X-RosetteAPI-/
+  CUSTOM_HEADER_PREFIX_BABELSTREET = /^X-BabelStreetAPI-/
+
+  # Alternate API URL
   attr_reader :alternate_url
-  # Rosette API HTTP client
+  # API HTTP client
   attr_reader :http_client
   # Parameters to build the body of the request from
   attr_accessor :params
-  # Rosette API key
+  # API key
   attr_accessor :user_key
-  # Rosette API binding version
+  # API binding version
   attr_accessor :binding_version
   # User-Agent string
   attr_reader :user_agent
@@ -28,14 +56,14 @@ class RequestBuilder
     @http_client = http_client
     @binding_version = binding_version
     @params = params
-    @user_agent = 'Ruby/' + binding_version + '/' + RUBY_VERSION
+    @user_agent = "Ruby/#{binding_version}/#{RUBY_VERSION}"
 
     return unless url_parameters
 
-    @alternate_url = @alternate_url + '?' + URI.encode_www_form(url_parameters)
+    @alternate_url = "#{@alternate_url}?#{URI.encode_www_form(url_parameters)}"
   end
 
-  # Prepares a plain POST request for Rosette API.
+  # Prepares a plain POST request for Analytics API.
   #
   # ==== Attributes
   #
@@ -50,8 +78,8 @@ class RequestBuilder
       # Not ideal.  Consider switching to a different library.
       # https://stackoverflow.com/a/11802674
       raise RosetteAPIError.new(
-        'connectionError',
-        'Failed to establish connection with Rosette server.'
+        CONNECTION_ERROR_CODE,
+        CONNECTION_ERROR_MESSAGE
       )
     end
 
@@ -60,30 +88,32 @@ class RequestBuilder
     if custom_headers
       keys_array = custom_headers.keys
       keys_array.each do |key|
-        if key.to_s =~ /^X-RosetteAPI-/
+        if key.to_s =~ CUSTOM_HEADER_PREFIX_ROSETTE || key.to_s =~ CUSTOM_HEADER_PREFIX_BABELSTREET
           request[key] = custom_headers[key]
         else
           raise RosetteAPIError.new(
-            'invalidHeader',
-            'Custom header must begin with "X-RosetteAPI-"'
+            INVALID_HEADER_CODE,
+            INVALID_HEADER_MESSAGE
           )
         end
       end
       params.delete 'customHeaders'
     end
 
-    request['X-RosetteAPI-Key'] = @user_key
-    request['Content-Type'] = 'application/json'
-    request['Accept'] = 'application/json'
-    request['User-Agent'] = @user_agent
-    request['X-RosetteAPI-Binding'] = 'ruby'
-    request['X-RosetteAPI-Binding-Version'] = @binding_version
+    request[HEADER_API_KEY] = @user_key
+    request[HEADER_CONTENT_TYPE] = CONTENT_TYPE_JSON
+    request[HEADER_ACCEPT] = ACCEPT_JSON
+    request[HEADER_USER_AGENT] = @user_agent
+    request[HEADER_BINDING_LEGACY] = BINDING_NAME
+    request[HEADER_BINDING] = BINDING_NAME
+    request[HEADER_BINDING_VERSION_LEGACY] = @binding_version
+    request[HEADER_BINDING_VERSION] = @binding_version
     request.body = params.to_json
 
     [@http_client, request]
   end
 
-  # Prepares a multipart/form-data POST request for Rosette API.
+  # Prepares a multipart/form-data POST request for Analytics API.
   #
   # ==== Attributes
   #
@@ -91,29 +121,25 @@ class RequestBuilder
   #
   # Returns a HTTP connection and the built POST request.
   def prepare_multipart_request(params)
-    begin
-      file = File.open params['filePath'], 'r'
-      text = file.read
-    rescue StandardError => e
-      raise RosetteAPIError.new('readMultipartError', e)
-    end
+    text = read_multipart_file params['filePath']
 
     boundary = SecureRandom.hex
     post_body = []
-    params.delete 'filePath'
-    request_file = params.to_json
 
     # Add the content data
     post_body << "--#{boundary}\r\n"
     post_body << 'Content-Disposition: form-data; name="content"; ' \
-                 "filename=\"#{File.basename(file)}\"\r\n"
-    post_body << "Content-Type: text/plain\r\n\r\n"
+                 "filename=\"#{File.basename(params['filePath'])}\"\r\n"
+    post_body << "#{HEADER_CONTENT_TYPE}: #{CONTENT_TYPE_TEXT_PLAIN}\r\n\r\n"
     post_body << text
 
     # Add the request data
+    params.delete 'filePath'
+    request_file = params.to_json
+
     post_body << "\r\n\r\n--#{boundary}\r\n"
     post_body << "Content-Disposition: form-data; name=\"request\"\r\n"
-    post_body << "Content-Type: application/json\r\n\r\n"
+    post_body << "#{HEADER_CONTENT_TYPE}: #{CONTENT_TYPE_JSON}\r\n\r\n"
     post_body << request_file
     post_body << "\r\n\r\n--#{boundary}--\r\n"
 
@@ -125,8 +151,8 @@ class RequestBuilder
       # Not ideal.  Consider switching to a different library.
       # https://stackoverflow.com/a/11802674
       raise RosetteAPIError.new(
-        'connectionError',
-        'Failed to establish connection with Rosette API server.'
+        CONNECTION_ERROR_CODE,
+        CONNECTION_ERROR_MESSAGE
       )
     end
 
@@ -134,30 +160,43 @@ class RequestBuilder
     unless params['customHeaders'].nil?
       keys_array = params['customHeaders'].keys
       keys_array.each do |k|
-        if k.to_s =~ /^X-RosetteAPI-/
+        if k.to_s =~ CUSTOM_HEADER_PREFIX_ROSETTE || k.to_s =~ CUSTOM_HEADER_PREFIX_BABELSTREET
           request.add_field k, params['customHeaders'][k]
         else
           raise RosetteAPIError.new(
-            'invalidHeader',
-            'Custom header must begin with "X-RosetteAPI-"'
+            INVALID_HEADER_CODE,
+            INVALID_HEADER_MESSAGE
           )
         end
       end
       params.delete 'customHeaders'
     end
 
-    request.add_field 'Content-Type',
-                      "multipart/form-data; boundary=#{boundary}"
-    request.add_field 'User-Agent', @user_agent
-    request.add_field 'X-RosetteAPI-Key', @user_key
-    request.add_field 'X-RosetteAPI-Binding', 'ruby'
-    request.add_field 'X-RosetteAPI-Binding-Version', @binding_version
+    request.add_field HEADER_CONTENT_TYPE,
+                      "#{MULTIPART_FORM_DATA}; boundary=#{boundary}"
+    request.add_field HEADER_USER_AGENT, @user_agent
+    request.add_field HEADER_API_KEY, @user_key
+    request.add_field HEADER_BINDING_LEGACY, BINDING_NAME
+    request.add_field HEADER_BINDING, BINDING_NAME
+    request.add_field HEADER_BINDING_VERSION_LEGACY, @binding_version
+    request.add_field HEADER_BINDING_VERSION, @binding_version
     request.body = post_body.join
 
     [@http_client, request]
   end
 
-  # Sends a GET request to Rosette API.
+  # Reads the content of a file given its path.
+  #
+  # Returns the content of the file or raises error if encountered.
+  def read_multipart_file(file_path)
+    File.open(file_path, 'r') do |f|
+      return f.read
+    end
+  rescue StandardError => e
+    raise RosetteAPIError.new(READ_MULTIPART_ERROR_CODE, e)
+  end
+
+  # Sends a GET request to Analytics API.
   #
   # Returns JSON response or raises RosetteAPIError if encountered.
   def send_get_request
@@ -168,17 +207,17 @@ class RequestBuilder
       # Not ideal.  Consider switching to a different library.
       # https://stackoverflow.com/a/11802674
       raise RosetteAPIError.new(
-        'connectionError',
-        'Failed to establish connection with Rosette API server.'
+        CONNECTION_ERROR_CODE,
+        CONNECTION_ERROR_MESSAGE
       )
     end
-    request['X-RosetteAPI-Key'] = @user_key
-    request['User-Agent'] = @user_agent
+    request[HEADER_API_KEY] = @user_key
+    request[HEADER_USER_AGENT] = @user_agent
 
     get_response @http_client, request
   end
 
-  # Sends a POST request to Rosette API.
+  # Sends a POST request to Analytics API.
   #
   # Returns JSON response or raises RosetteAPIError if encountered.
   def send_post_request
@@ -197,22 +236,23 @@ class RequestBuilder
   #
   # * +http+ - HTTP connection.
   #
-  # * +request+ - Prepared Rosette API request.
+  # * +request+ - Prepared API request.
   #
   # Returns JSON response or raises RosetteAPIError if encountered.
   def get_response(http, request)
     response = http.request request
 
-    if response.code != '200'
-      message = JSON.parse(response.body)['message']
-      code = JSON.parse(response.body)['code']
-      raise RosetteAPIError.new code, message
-    else
+    if response.code == '200'
       response_headers = {}
       response.header.each_header { |key, value| response_headers[key] = value }
       response_headers = { responseHeaders: response_headers }
 
       JSON.parse(response.body).merge(response_headers)
+    else
+      parsed_body = JSON.parse(response.body)
+      message = parsed_body['message']
+      code = parsed_body['code']
+      raise RosetteAPIError.new code, message
     end
   end
 end