Feat: Custom Dictionaries (#445)

* feat(cust-dictionaries): start implementing methods and CTS

* feat(custom-dictionaries): finish tests

* feat(dictionaries): adds doc blocks and wrap up tests

* fix PR

Author: chloelbn

lib/algolia.rb

@@ -20,6 +20,7 @@
 require 'algolia/responses/add_api_key_response'
 require 'algolia/responses/update_api_key_response'
 require 'algolia/responses/delete_api_key_response'
+require 'algolia/responses/dictionary_response'
 require 'algolia/responses/restore_api_key_response'
 require 'algolia/responses/multiple_batch_indexing_response'
 require 'algolia/responses/multiple_response'

lib/algolia/responses/dictionary_response.rb

@@ -0,0 +1,33 @@
+module Algolia
+  class DictionaryResponse < BaseResponse
+    include CallType
+
+    attr_reader :raw_response
+
+    # @param client [Search::Client] Algolia Search Client used for verification
+    # @param response [Hash] Raw response from the client
+    #
+    def initialize(client, response)
+      @client       = client
+      @raw_response = response
+      @done         = false
+    end
+
+    # Wait for the task to complete
+    #
+    # @param opts [Hash] contains extra parameters to send with your query
+    #
+    def wait(_opts = {})
+      until @done
+        res    = @client.custom_request({}, path_encode('/1/task/%s', @raw_response[:taskID]), :GET, READ)
+        status = get_option(res, 'status')
+        if status == 'published'
+          @done = true
+        end
+        sleep(Defaults::WAIT_TASK_DEFAULT_TIME_BEFORE_RETRY / 1000)
+      end
+
+      self
+    end
+  end
+end

lib/algolia/search_client.rb

@@ -80,7 +80,7 @@ def get_task_status(index_name, task_id, opts = {})
       end
 
       # # # # # # # # # # # # # # # # # # # # #
-      # MISC
+      # INDEX METHODS
       # # # # # # # # # # # # # # # # # # # # #
 
       # Initialize an index with a given name
@@ -594,12 +594,185 @@ def pending_mappings?(opts = {})
         @transporter.read(:GET, '/1/clusters/mapping/pending' + handle_params({ getClusters: retrieve_mappings }), {}, request_options)
       end
 
-      #
       # Aliases the pending_mappings? method
       #
       alias_method :has_pending_mappings, :pending_mappings?
 
+      # # # # # # # # # # # # # # # # # # # # #
+      # CUSTOM DICTIONARIES METHODS
+      # # # # # # # # # # # # # # # # # # # # #
+
+      # Save entries for a given dictionary
+      #
+      # @param dictionary [String] dictionary name. Can be either 'stopwords', 'plurals' or 'compounds'
+      # @param dictionary_entries [Array<Hash>] array of dictionary entries
+      # @param opts [Hash] contains extra parameters to send with your query
+      #
+      # @return DictionaryResponse
+      #
+      def save_dictionary_entries(dictionary, dictionary_entries, opts = {})
+        response = @transporter.write(
+          :POST,
+          path_encode('/1/dictionaries/%s/batch', dictionary),
+          { clearExistingDictionaryEntries: false, requests: chunk('addEntry', dictionary_entries) },
+          opts
+        )
+
+        DictionaryResponse.new(self, response)
+      end
+
+      # Save entries for a given dictionary and wait for the task to finish
+      #
+      # @param dictionary [String] dictionary name. Can be either 'stopwords', 'plurals' or 'compounds'
+      # @param dictionary_entries [Array<Hash>] array of dictionary entries
+      # @param opts [Hash] contains extra parameters to send with your query
+      #
+      def save_dictionary_entries!(dictionary, dictionary_entries, opts = {})
+        response = save_dictionary_entries(dictionary, dictionary_entries, opts)
+
+        response.wait(opts)
+      end
+
+      # Replace entries for a given dictionary
+      #
+      # @param dictionary [String] dictionary name. Can be either 'stopwords', 'plurals' or 'compounds'
+      # @param dictionary_entries [Array<Hash>] array of dictionary entries
+      # @param opts [Hash] contains extra parameters to send with your query
+      #
+      # @return DictionaryResponse
+      #
+      def replace_dictionary_entries(dictionary, dictionary_entries, opts = {})
+        response = @transporter.write(
+          :POST,
+          path_encode('/1/dictionaries/%s/batch', dictionary),
+          { clearExistingDictionaryEntries: true, requests: chunk('addEntry', dictionary_entries) },
+          opts
+        )
+
+        DictionaryResponse.new(self, response)
+      end
+
+      # Replace entries for a given dictionary and wait for the task to finish
+      #
+      # @param dictionary [String] dictionary name. Can be either 'stopwords', 'plurals' or 'compounds'
+      # @param dictionary_entries [Array<Hash>] array of dictionary entries
+      # @param opts [Hash] contains extra parameters to send with your query
+      #
+      def replace_dictionary_entries!(dictionary, dictionary_entries, opts = {})
+        response = replace_dictionary_entries(dictionary, dictionary_entries, opts)
+
+        response.wait(opts)
+      end
+
+      # Delete entries for a given dictionary
+      #
+      # @param dictionary [String] dictionary name. Can be either 'stopwords', 'plurals' or 'compounds'
+      # @param object_ids [Array<Hash>] array of object ids
+      # @param opts [Hash] contains extra parameters to send with your query
+      #
+      # @return DictionaryResponse
+      #
+      def delete_dictionary_entries(dictionary, object_ids, opts = {})
+        request  = object_ids.map do |object_id|
+          { objectID: object_id }
+        end
+        response = @transporter.write(
+          :POST,
+          path_encode('/1/dictionaries/%s/batch', dictionary),
+          { clearExistingDictionaryEntries: false, requests: chunk('deleteEntry', request) },
+          opts
+        )
+
+        DictionaryResponse.new(self, response)
+      end
+
+      # Delete entries for a given dictionary and wait for the task to finish
+      #
+      # @param dictionary [String] dictionary name. Can be either 'stopwords', 'plurals' or 'compounds'
+      # @param object_ids [Array<Hash>] array of object ids
+      # @param opts [Hash] contains extra parameters to send with your query
       #
+      def delete_dictionary_entries!(dictionary, object_ids, opts = {})
+        response = delete_dictionary_entries(dictionary, object_ids, opts)
+
+        response.wait(opts)
+      end
+
+      # Clear all entries for a given dictionary
+      #
+      # @param dictionary [String] dictionary name. Can be either 'stopwords', 'plurals' or 'compounds'
+      # @param opts [Hash] contains extra parameters to send with your query
+      #
+      # @return DictionaryResponse
+      #
+      def clear_dictionary_entries(dictionary, opts = {})
+        replace_dictionary_entries(dictionary, [], opts)
+      end
+
+      # Clear all entries for a given dictionary and wait for the task to finish
+      #
+      # @param dictionary [String] dictionary name. Can be either 'stopwords', 'plurals' or 'compounds'
+      # @param opts [Hash] contains extra parameters to send with your query
+      #
+      def clear_dictionary_entries!(dictionary, opts = {})
+        response = replace_dictionary_entries(dictionary, [], opts)
+
+        response.wait(opts)
+      end
+
+      # Search entries for a given dictionary
+      #
+      # @param dictionary [String] dictionary name. Can be either 'stopwords', 'plurals' or 'compounds'
+      # @param query [String] query to send
+      # @param opts [Hash] contains extra parameters to send with your query
+      #
+      def search_dictionary_entries(dictionary, query, opts = {})
+        @transporter.read(
+          :POST,
+          path_encode('/1/dictionaries/%s/search', dictionary),
+          { query: query },
+          opts
+        )
+      end
+
+      # Set settings for all the dictionaries
+      #
+      # @param dictionary_settings [Hash]
+      # @param opts [Hash] contains extra parameters to send with your query
+      #
+      # @return DictionaryResponse
+      #
+      def set_dictionary_settings(dictionary_settings, opts = {})
+        response = @transporter.write(:PUT, '/1/dictionaries/*/settings', dictionary_settings, opts)
+
+        DictionaryResponse.new(self, response)
+      end
+
+      # Set settings for all the dictionaries and wait for the task to finish
+      #
+      # @param dictionary_settings [Hash]
+      # @param opts [Hash] contains extra parameters to send with your query
+      #
+      # @return DictionaryResponse
+      #
+      def set_dictionary_settings!(dictionary_settings, opts = {})
+        response = set_dictionary_settings(dictionary_settings, opts)
+
+        response.wait(opts)
+      end
+
+      # Retrieve settings for all the dictionaries
+      #
+      # @param opts [Hash] contains extra parameters to send with your query
+      #
+      def get_dictionary_settings(opts = {})
+        @transporter.read(:GET, '/1/dictionaries/*/settings', {}, opts)
+      end
+
+      # # # # # # # # # # # # # # # # # # # # #
+      # MISC METHODS
+      # # # # # # # # # # # # # # # # # # # # #
+
       # Method available to make custom requests to the API
       #
       def custom_request(data, uri, method, call_type, opts = {})

test/algolia/integration/search_client_test.rb

@@ -1,3 +1,4 @@
+require 'securerandom'
 require_relative 'base_test'
 
 class SearchClientTest < BaseTest
@@ -367,5 +368,96 @@ def test_expired_secured_api_keys
         assert_equal 'The SecuredAPIKey doesn\'t have a validUntil parameter.', exception.message
       end
     end
+
+    describe 'Custom Dictionaries' do
+      def before_all
+        @client = Algolia::Search::Client.create(APPLICATION_ID_2, ADMIN_KEY_2)
+      end
+
+      def test_stopwords_dictionaries
+        entry_id = SecureRandom.hex
+        assert_equal 0, @client.search_dictionary_entries('stopwords', entry_id)[:nbHits]
+
+        entry = {
+          objectID: entry_id,
+          language: 'en',
+          word: 'down'
+        }
+        @client.save_dictionary_entries!('stopwords', [entry])
+
+        stopwords = @client.search_dictionary_entries('stopwords', entry_id)
+        assert_equal 1, stopwords[:nbHits]
+        assert_equal stopwords[:hits][0][:objectID], entry[:objectID]
+        assert_equal stopwords[:hits][0][:word], entry[:word]
+
+        @client.delete_dictionary_entries!('stopwords', [entry_id])
+        assert_equal 0, @client.search_dictionary_entries('stopwords', entry_id)[:nbHits]
+
+        old_dictionary_state   = @client.search_dictionary_entries('stopwords', '')
+        old_dictionary_entries = old_dictionary_state[:hits].map do |hit|
+          hit.reject { |key| key == :type }
+        end
+
+        @client.save_dictionary_entries!('stopwords', [entry])
+        assert_equal 1, @client.search_dictionary_entries('stopwords', entry_id)[:nbHits]
+
+        @client.replace_dictionary_entries!('stopwords', old_dictionary_entries)
+        assert_equal 0, @client.search_dictionary_entries('stopwords', entry_id)[:nbHits]
+
+        stopwords_settings = {
+          disableStandardEntries: {
+            stopwords: {
+              en: true
+            }
+          }
+        }
+
+        @client.set_dictionary_settings!(stopwords_settings)
+
+        assert_equal @client.get_dictionary_settings, stopwords_settings
+      end
+
+      def test_plurals_dictionaries
+        entry_id = SecureRandom.hex
+        assert_equal 0, @client.search_dictionary_entries('plurals', entry_id)[:nbHits]
+
+        entry = {
+          objectID: entry_id,
+          language: 'fr',
+          words: %w(cheval chevaux)
+        }
+        @client.save_dictionary_entries!('plurals', [entry])
+
+        plurals = @client.search_dictionary_entries('plurals', entry_id)
+        assert_equal 1, plurals[:nbHits]
+        assert_equal plurals[:hits][0][:objectID], entry[:objectID]
+        assert_equal plurals[:hits][0][:words], entry[:words]
+
+        @client.delete_dictionary_entries!('plurals', [entry_id])
+        assert_equal 0, @client.search_dictionary_entries('plurals', entry_id)[:nbHits]
+      end
+
+      def test_compounds_dictionaries
+        entry_id = SecureRandom.hex
+        assert_equal 0, @client.search_dictionary_entries('compounds', entry_id)[:nbHits]
+
+        entry = {
+          objectID: entry_id,
+          language: 'de',
+          word: 'kopfschmerztablette',
+          decomposition: %w(kopf schmerz tablette)
+        }
+        @client.save_dictionary_entries!('compounds', [entry])
+
+        compounds = @client.search_dictionary_entries('compounds', entry_id)
+        assert_equal 1, compounds[:nbHits]
+        assert_equal compounds[:hits][0][:objectID], entry[:objectID]
+        assert_equal compounds[:hits][0][:word], entry[:word]
+        assert_equal compounds[:hits][0][:decomposition], entry[:decomposition]
+
+        @client.delete_dictionary_entries!('compounds', [entry_id])
+        assert_equal 0, @client.search_dictionary_entries('compounds', entry_id)[:nbHits]
+      end
+    end
   end
 end