Add OxfordDictionary::Endpoints::Translations

lib/oxford_dictionary/client.rb

@@ -5,6 +5,7 @@
 
 require 'oxford_dictionary/endpoints/entries'
 require 'oxford_dictionary/endpoints/lemmas'
+require 'oxford_dictionary/endpoints/translations'
 
 module OxfordDictionary
   # The client object to interact with
@@ -28,11 +29,11 @@ def initialize(params)
     def entry(*args)
       if args.first.is_a?(Hash)
         args = args.first
-          entry_endpoint.entry(
-            word: args[:word],
-            dataset: args[:dataset],
-            params: args[:params]
-          )
+        entry_endpoint.entry(
+          word: args[:word],
+          dataset: args[:dataset],
+          params: args[:params]
+        )
       else
         warn '''
           The V1 interface for this library is DEPRECATED and will become
@@ -56,13 +57,28 @@ def lemma(word:, language:, params: {})
       lemma_endpoint.lemma(word: word, language: language, params: params)
     end
 
+    def translation(word:, source_language:, target_language:, params: {})
+      translation_endpoint.translation(
+        word: word,
+        source_language: source_language,
+        target_language: target_language,
+        params: params
+      )
+    end
+
     private
 
     def lemma_endpoint
       @lemma_endpoint ||=
         OxfordDictionary::Endpoints::Lemmas.new(request_client: request_client)
     end
 
+    def translation_endpoint
+      @translation_endpoint ||= OxfordDictionary::Endpoints::Translations.new(
+        request_client: request_client
+      )
+    end
+
     def entry_endpoint
       @entry_endpoint ||=
         OxfordDictionary::Endpoints::Entries.new(request_client: request_client)

lib/oxford_dictionary/endpoints/entry_endpoint.rb

@@ -48,6 +48,13 @@ def entry_antonyms_synonyms(query, params = {})
       end
 
       def entry_translations(query, params = {})
+        warn '''
+        Client#entry_translations is DEPRECATED and will become non-functional
+        on June 30, 2019. Use Client#translation instead. Reference
+        https://github.com/swcraig/oxford-dictionary/pull/12 for more
+        information. Check out OxfordDictionary::Endpoints::Translations for the
+        interface to use.
+        '''
         params.key?(:translations) || params[:translations] = 'es'
         entry_request(query, params)
       end

lib/oxford_dictionary/endpoints/translations.rb

@@ -0,0 +1,32 @@
+require 'oxford_dictionary/deserialize'
+
+module OxfordDictionary
+  module Endpoints
+    class Translations
+      ENDPOINT = 'translations'.freeze
+
+      def initialize(request_client:)
+        @request_client = request_client
+      end
+
+      def translation(word:, source_language:, target_language:, params: {})
+        query_string =
+          "#{ENDPOINT}/#{source_language}/#{target_language}/#{word}"
+        uri = URI(query_string)
+
+        unless params.empty?
+          uri.query = URI.encode_www_form(params)
+        end
+
+        response = @request_client.get(uri: uri)
+        deserialize.call(response.body)
+      end
+
+      private
+
+      def deserialize
+        @deserialize ||= OxfordDictionary::Deserialize.new
+      end
+    end
+  end
+end

spec/client_spec.rb

@@ -53,6 +53,32 @@
     end
   end
 
+  describe '#translation' do
+    subject do
+      client.translation(
+        word: word,
+        source_language: source_language,
+        target_language: target_language,
+        params: params)
+    end
+
+    let(:word) { 'ace' }
+    let(:source_language) { 'en' }
+    let(:target_language) { 'es' }
+    let(:params) { {} }
+
+    it 'calls the Translations endpoint with correct arguments' do
+      expect_any_instance_of(OxfordDictionary::Endpoints::Translations).
+        to receive(:translation).
+        with(word: word,
+             source_language: source_language,
+             target_language: target_language,
+             params: params)
+
+      subject
+    end
+  end
+
   describe '#entry_snake_case' do
     let(:client) { described_class.new(app_id: app_id, app_key: app_key) }
     subject do

spec/endpoints/translations_spec.rb

@@ -0,0 +1,75 @@
+require 'spec_helper'
+require 'oxford_dictionary/endpoints/translations'
+
+# Spec dependencies
+require 'oxford_dictionary/request'
+
+RSpec.describe OxfordDictionary::Endpoints::Translations do
+  let(:request_client) do
+    OxfordDictionary::Request.
+      new(app_id: ENV['APP_ID'], app_key: ENV['APP_KEY'])
+  end
+
+  let(:endpoint) { described_class.new(request_client: request_client) }
+
+  let(:word) { 'ace' }
+  let(:source_language) { 'en' }
+  let(:target_language) { 'es' }
+  let(:params) { {} }
+
+  # The translations endpoint is only avaiable to the paid tier
+  # If someone with a paid tier account would like to contribute, please
+  # feel free remove this double (and the stub in the tests), uncomment the
+  # sections that run VCR against the live endpoint, and PR the resulting files
+  let(:response_double) { double(body: {}.to_json) }
+
+  describe '#translation' do
+    subject do
+      endpoint.translation(
+        word: word,
+        source_language: source_language,
+        target_language: target_language,
+        params: params
+      )
+    end
+
+    it 'calls API as expected', :aggregate_failures do
+      expected_uri =
+        URI("translations/#{source_language}/#{target_language}/#{word}")
+
+      expect(request_client).to receive(:get).
+        with(uri: expected_uri).
+        and_return(response_double)
+
+      subject
+
+      # VCR.use_cassette('translations#translation') do
+      #   response = subject
+      #   expect(response).to be_an(OpenStruct)
+      #   expect(response.results.first.id).to eq(word)
+      #   expect(response.results.first.lexicalEntries).to all(be_an(OpenStruct))
+      # end
+    end
+
+    context 'when the params include strictMatch: true' do
+      let(:params) { { strictMatch: true } }
+
+      it 'only returns strict match translations', :aggregate_failures do
+        expected_uri =
+          URI("translations/#{source_language}/#{target_language}/#{word}?strictMatch=true")
+
+        expect(request_client).to receive(:get).
+          with(uri: expected_uri).
+          and_return(response_double)
+
+        subject
+
+        # VCR.use_cassette('translations#translation-strict') do
+        #   response = subject
+        #   expect(response).to be_an(OpenStruct)
+        #   expect(response.results.first.id).to eq(word)
+        # end
+      end
+    end
+  end
+end