Add OxfordDictionary::Endpoints::Sentences

lib/oxford_dictionary/client.rb

@@ -6,6 +6,7 @@
 require 'oxford_dictionary/endpoints/entries'
 require 'oxford_dictionary/endpoints/lemmas'
 require 'oxford_dictionary/endpoints/translations'
+require 'oxford_dictionary/endpoints/sentences'
 
 module OxfordDictionary
   # The client object to interact with
@@ -66,6 +67,10 @@ def translation(word:, source_language:, target_language:, params: {})
       )
     end
 
+    def sentence(word:, language:, params: {})
+      sentence_endpoint.sentence(word: word, language: language, params: params)
+    end
+
     private
 
     def lemma_endpoint
@@ -84,6 +89,12 @@ def entry_endpoint
         OxfordDictionary::Endpoints::Entries.new(request_client: request_client)
     end
 
+    def sentence_endpoint
+      @sentence_endpoint ||= OxfordDictionary::Endpoints::Sentences.new(
+        request_client: request_client
+      )
+    end
+
     def request_client
       @request_client ||=
         OxfordDictionary::Request.new(app_id: @app_id, app_key: @app_key)

lib/oxford_dictionary/endpoints/entry_endpoint.rb

@@ -28,6 +28,14 @@ def entry_pronunciations(query, params = {})
       end
 
       def entry_sentences(query, params = {})
+        warn '''
+        Client#entry_sentences is DEPRECATED and will become non-functional
+        on June 30, 2019. Use Client#sentence instead. Reference
+        https://github.com/swcraig/oxford-dictionary/pull/13 for more
+        information. Check out OxfordDictionary::Endpoints::Sentences for the
+        interface to use.
+        '''
+
         params[:end] = 'sentences'
         entry_request(query, params)
       end

lib/oxford_dictionary/endpoints/sentences.rb

@@ -0,0 +1,31 @@
+require 'oxford_dictionary/deserialize'
+
+module OxfordDictionary
+  module Endpoints
+    class Sentences
+      ENDPOINT = 'sentences'.freeze
+
+      def initialize(request_client:)
+        @request_client = request_client
+      end
+
+      def sentence(word:, language:, params: {})
+        query_string = "#{ENDPOINT}/#{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

@@ -79,6 +79,21 @@
     end
   end
 
+  describe '#sentence' do
+    subject { client.sentence(word: word, language: language, params: params) }
+    let(:word) { 'ace' }
+    let(:language) { 'en' }
+    let(:params) { {} }
+
+    it 'calls the Sentences endpoint with correct arguments' do
+      expect_any_instance_of(OxfordDictionary::Endpoints::Sentences).
+        to receive(:sentence).
+        with(word: word, language: 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/sentences_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+require 'oxford_dictionary/endpoints/sentences'
+
+# Spec dependencies
+require 'oxford_dictionary/request'
+
+RSpec.describe OxfordDictionary::Endpoints::Sentences 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(:language) { 'en' }
+  let(:params) { {} }
+
+  # The sentences 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 '#sentence' do
+    subject do
+      endpoint.sentence(word: word, language: language, params: params)
+    end
+
+    it 'calls API as expected', :aggregate_failures do
+      expected_uri = URI("sentences/#{language}/#{word}")
+
+      expect(request_client).to receive(:get).
+        with(uri: expected_uri).
+        and_return(response_double)
+
+      subject
+
+      # VCR.use_cassette('sentences#sentence') 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
+  end
+end