twingly-search 3.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4a32c03b5a124011f9486d4724a9390f74fd88f2
-  data.tar.gz: b7c26d1ba53842a58e40f25ae54abbe9c0dee8f7
+  metadata.gz: dd9953d1e03a6e3b8876f3a4b86580ddcfeeeccf
+  data.tar.gz: 36f8ccb71ca25e1016d00e366652e06dc71b6321
 SHA512:
-  metadata.gz: 5a3ffe5d6257cb17d9e32df29cac7e9014829b99d71aef1c0adef5cae4d338018dcbc378af4d5b4d299753851fac6c4b10c24e38ebea8e23a950647d8c250134
-  data.tar.gz: 9142bf21df1a9655f89c4df65ab3072a2bf7e3efc054cec70cb332ea7c37a83fb29d7442b77d40707e8843512d2c51fe5dfdde5b3741c8675aff8aa7fee258da
+  metadata.gz: 525c3009c34290b6a86a6a397c9e907d9defbf7089e82e0786274d0c46146d79d4bf9d69cb673120ebd50ea1f10626a13b94d5e113590095f1c557edbc6380ef
+  data.tar.gz: 3df9d3ddd711c7185005a81c93ce3fb4b362a7a526698a2203e475c2e6234054e054269ebb2d45aedb44bc4c31ea88d083598952debd78af2c63f38dcc680edd

data/.gitignore

@@ -2,3 +2,5 @@
 Gemfile.lock
 .ruby-version
 *.gem
+.yardoc
+doc/

data/.travis.yml

@@ -1,10 +1,11 @@
 language: ruby
 cache: bundler
 rvm:
-- 1.9.3
-- 2.0.0
-- 2.1
-- 2.2
+  - 1.9.3
+  - 2.0.0
+  - 2.1
+  - 2.2
+  - jruby-9.0.0.0
 deploy:
   provider: rubygems
   api_key:

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Change Log
 
+## [v4.0.0](https://github.com/twingly/twingly-search-api-ruby/tree/v4.0.0)
+
+[Full Changelog](https://github.com/twingly/twingly-search-api-ruby/compare/v3.0.0...v4.0.0)
+
+**Implemented enhancements:**
+
+- Add JRuby 9000 to supported Ruby versions [\#27](https://github.com/twingly/twingly-search-api-ruby/issues/27)
+- Rename analytics to search [\#21](https://github.com/twingly/twingly-search-api-ruby/issues/21)
+
+**Fixed bugs:**
+
+- Handle non-XML responses from server [\#31](https://github.com/twingly/twingly-search-api-ruby/issues/31)
+- Changelog is not generated correctly [\#25](https://github.com/twingly/twingly-search-api-ruby/issues/25)
+
+**Merged pull requests:**
+
+- Example script: Retry on server error [\#35](https://github.com/twingly/twingly-search-api-ruby/pull/35) ([jage](https://github.com/jage))
+- Yield self [\#34](https://github.com/twingly/twingly-search-api-ruby/pull/34) ([roback](https://github.com/roback))
+- Handle non-XML responses from server [\#33](https://github.com/twingly/twingly-search-api-ruby/pull/33) ([roback](https://github.com/roback))
+- Add YARD documentation comments [\#32](https://github.com/twingly/twingly-search-api-ruby/pull/32) ([roback](https://github.com/roback))
+- Test with JRuby 9000 on travis [\#30](https://github.com/twingly/twingly-search-api-ruby/pull/30) ([roback](https://github.com/roback))
+- Handle exceptions [\#29](https://github.com/twingly/twingly-search-api-ruby/pull/29) ([roback](https://github.com/roback))
+- Let client handle api call [\#28](https://github.com/twingly/twingly-search-api-ruby/pull/28) ([roback](https://github.com/roback))
+- Cleanup [\#26](https://github.com/twingly/twingly-search-api-ruby/pull/26) ([roback](https://github.com/roback))
+- Show deprecation warnings for twingly-analytics [\#23](https://github.com/twingly/twingly-search-api-ruby/pull/23) ([roback](https://github.com/roback))
+
+## [v3.0.0](https://github.com/twingly/twingly-search-api-ruby/tree/v3.0.0) (2015-11-20)
+[Full Changelog](https://github.com/twingly/twingly-search-api-ruby/compare/2.0.1...v3.0.0)
+
+**Implemented enhancements:**
+
+- Improve "Development and release" section in README [\#19](https://github.com/twingly/twingly-search-api-ruby/issues/19)
+
+**Merged pull requests:**
+
+- Rename analytics to search [\#24](https://github.com/twingly/twingly-search-api-ruby/pull/24) ([roback](https://github.com/roback))
+- Improve "Development and release" section in README [\#22](https://github.com/twingly/twingly-search-api-ruby/pull/22) ([roback](https://github.com/roback))
+- Rename analytics to search in readme [\#20](https://github.com/twingly/twingly-search-api-ruby/pull/20) ([roback](https://github.com/roback))
+
 ## [2.0.1](https://github.com/twingly/twingly-search-api-ruby/tree/2.0.1) (2015-09-24)
 [Full Changelog](https://github.com/twingly/twingly-search-api-ruby/compare/2.0.0...2.0.1)
 

data/README.md

@@ -1,7 +1,7 @@
 # Twingly Search API Ruby
 
-[![Build Status](https://travis-ci.org/twingly/twingly-analytics-api-ruby.png?branch=master)](https://travis-ci.org/twingly/twingly-analytics-api-ruby)
-[![Code Climate](https://codeclimate.com/github/twingly/twingly-analytics-api-ruby.png)](https://codeclimate.com/github/twingly/twingly-analytics-api-ruby)
+[![Build Status](https://travis-ci.org/twingly/twingly-search-api-ruby.png?branch=master)](https://travis-ci.org/twingly/twingly-search-api-ruby)
+[![Code Climate](https://codeclimate.com/github/twingly/twingly-search-api-ruby/badges/gpa.svg)](https://codeclimate.com/github/twingly/twingly-search-api-ruby)
 
 A Ruby gem for Twingly's Search API (previously known as Analytics API). Twingly is a blog search service that provides a searchable API known as [Twingly Search API](https://developer.twingly.com/resources/search/).
 
@@ -9,25 +9,30 @@ A Ruby gem for Twingly's Search API (previously known as Analytics API). Twingly
 
 Install via RubyGems
 
-```Shell
+```shell
 gem install twingly-search
 ```
 
 Or add to your application's [Gemfile](http://bundler.io/gemfile.html) and then run `bundle`
 
-```Ruby
-gem 'twingly-search'
+```ruby
+gem "twingly-search"
 ```
 
 ## Usage
 
-```Ruby
-require 'twingly/search'
+```ruby
+require "twingly/search"
+
+client = Twingly::Search::Client.new do |client|
+  client.user_agent = "MyCompany/1.0"
+end
+
+query = client.query do |query|
+  query.pattern  = "github page-size:10"
+  query.language = "sv"
+end
 
-client = Twingly::Search::Client.new
-query = client.query
-query.pattern = 'github page-size:10'
-query.language = 'sv'
 result = query.execute
 => #<Twingly::Search::Result:0x3ff7adcbe3d4 @posts, @number_of_matches_returned=10, @number_of_matches_total=3035221>
 result.posts # will include all returned posts
@@ -35,14 +40,19 @@ result.posts # will include all returned posts
 
 The `twingly-search` gem talks to a commercial blog search API and requires an API key. Best practice is to set the `TWINGLY_SEARCH_KEY` environment variable to the obtained key. `Twingly::Search::Client` can be passed a key at initialization if your setup does not allow environment variables.
 
-Example code can be found in [examples/](examples/).
+To learn more about the features of this gem, read the [gem documentation] or check out the example code that can be found in [examples/](examples/).
 
-Too learn more about the capabilities of this API you should read the [Twingly Search API documentation](https://developer.twingly.com/resources/search/).
+To learn more about the capabilities of the API, please read the [Twingly Search API documentation].
+
+[gem documentation]: http://www.rubydoc.info/github/twingly/twingly-search-api-ruby
+[Twingly Search API documentation]: https://developer.twingly.com/resources/search/
 
 ## Requirements
 
-* API key, contact sales@twingly.com to get one
-* Ruby 1.9, 2.0, 2.1, 2.2
+* API key, contact sales@twingly.com via [twingly.com](http://www.twingly.com/try-for-free/) to get one
+* Ruby
+  * Ruby 1.9, 2.0, 2.1, 2.2
+  * JRuby 9000
 
 ## Development and release
 
@@ -53,6 +63,16 @@ Too learn more about the capabilities of this API you should read the [Twingly S
 
 [releases page]: https://github.com/twingly/twingly-search-api-ruby/releases
 
+### Documentation
+
+This gem is documented using [YARD]. To start a local YARD server run:
+
+    bundle exec rake yard:server
+
+The YARD server reloads the documentation automatically so there is no need to restart it when making changes.
+
+[YARD]: http://yardoc.org/
+
 ## License
 
 The MIT License (MIT)

data/Rakefile

@@ -16,8 +16,26 @@ GitHubChangelogGenerator::RakeTask.new(:changelog) do |config|
   config.project = "twingly-search-api-ruby"
 end
 
+namespace :yard do
+  require "yard"
+  require "yard/rake/yardoc_task"
+
+  desc "Generate Yardoc documentation"
+  YARD::Rake::YardocTask.new(:generate)
+
+  desc "Start a Yard server"
+  task :server do
+    sh("yard", "server", "--reload")
+  end
+end
+
+desc "Synonym for yard:generate"
+task yard: "yard:generate"
+
 desc "Synonym for spec"
-task :test => :spec
+task test: :spec
+
 desc "Synonym for spec"
-task :tests => :spec
-task :default => :spec
+task tests: :spec
+
+task default: :spec

data/examples/Gemfile

@@ -1,3 +1,4 @@
 source 'https://rubygems.org'
 
 gem 'twingly-search', path: '../'
+gem "retryable"

data/examples/find_all_posts_mentioning_github.rb

@@ -3,15 +3,22 @@ Bundler.require
 class SearchPostStream
   def initialize(keyword, language: nil)
     # Set environment variable TWINGLY_SEARCH_KEY
-    client = Twingly::Search::Client.new
-    @query = client.query
-    @query.language = language
-    @query.pattern = "sort-order:asc sort:published #{keyword}"
+    client = Twingly::Search::Client.new do |client|
+      client.user_agent = "MyCompany/1.0" # Set optional user agent
+    end
+
+    @query = client.query do |query|
+      query.language = language
+      query.pattern  = "sort-order:asc sort:published #{keyword}"
+    end
   end
 
+  # Run block for each blog post returned from api.
+  # Uses a sliding time-based window to get all results.
+  # @see https://developer.twingly.com/resources/search/#pagination
   def each
     loop do
-      result = @query.execute
+      result = execute_with_retry
       result.posts.each do |post|
         yield post
       end
@@ -21,6 +28,14 @@ class SearchPostStream
       @query.start_time = result.posts.last.published
     end
   end
+
+  private
+
+  def execute_with_retry
+    Retryable.retryable(on: Twingly::Search::ServerError) do
+      @query.execute
+    end
+  end
 end
 
 stream = SearchPostStream.new("(github) AND (hipchat OR slack)")

data/examples/hello_world.rb

@@ -2,9 +2,11 @@ Bundler.require
 
 # Set environment variable TWINGLY_SEARCH_KEY
 client = Twingly::Search::Client.new
-query = client.query
-query.pattern = '"hello world"'
-query.start_time = Time.now - (24 * 3600) # search last day
+query = client.query do |query|
+  query.pattern    = '"hello world"'
+  query.start_time = Time.now - (24 * 3600) # search last day
+end
+
 result = query.execute
 result.posts.each do |post|
   puts post.url

data/lib/twingly/search.rb

@@ -1,6 +1,7 @@
+require 'twingly/search/version'
+require 'twingly/search/error'
 require 'twingly/search/client'
 require 'twingly/search/query'
 require 'twingly/search/result'
 require 'twingly/search/parser'
 require 'twingly/search/post'
-require 'twingly/search/version'

data/lib/twingly/search/client.rb

@@ -1,19 +1,76 @@
+require "faraday"
+
 module Twingly
   module Search
+    # Twingly Search API client
     class Client
-      attr_accessor :api_key
+      attr_accessor :api_key, :user_agent
+
+      BASE_URL    = "https://api.twingly.com"
+      SEARCH_PATH = "/analytics/Analytics.ashx"
+
+      DEFAULT_USER_AGENT = "Twingly Search Ruby Client/#{VERSION}"
+
+      # Creates a new Twingly Search API client
+      #
+      # @param api_key [optional, String] the API key provided by Twingly.
+      #   If nil, reads api_key from environment (TWINGLY_SEARCH_KEY).
+      # @param options [Hash]
+      # @option options [String] :user_agent the user agent to be used
+      #    for all requests
+      # @raise [AuthError] if an API key is not set.
+      def initialize(api_key = nil, options = {})
+        @api_key    = api_key
+        @user_agent = options.fetch(:user_agent) { DEFAULT_USER_AGENT }
 
-      def initialize(api_key = nil)
-        @api_key = api_key || env_api_key || fail("Missing API key")
+        yield self if block_given?
+
+        @api_key ||= env_api_key || api_key_missing
+      end
+
+      # Returns a new Query object connected to this client
+      #
+      # @yield [Query]
+      # @return [Query]
+      def query(&block)
+        Query.new(self, &block)
       end
 
-      def query
-        Query.new(self)
+      # Executes the given Query and returns the result
+      #
+      # This method should not be called manually, as that is
+      # handled by {Query#execute}.
+      #
+      # @param query [Query] the query to be executed.
+      # @return [Result]
+      def execute_query(query)
+        response_body = get_response(query).body
+        Parser.new.parse(response_body)
       end
-    private
+
+      # @return [String] the API endpoint URL
+      def endpoint_url
+        "#{BASE_URL}#{SEARCH_PATH}"
+      end
+
+      private
+
       def env_api_key
         ENV['TWINGLY_SEARCH_KEY']
       end
+
+      def get_response(query)
+        connection = Faraday.new(url: BASE_URL) do |faraday|
+          faraday.request :url_encoded
+          faraday.adapter Faraday.default_adapter
+        end
+        connection.headers[:user_agent] = user_agent
+        connection.get(SEARCH_PATH, query.request_parameters)
+      end
+
+      def api_key_missing
+        fail AuthError, "No API key has been provided."
+      end
     end
   end
 end

data/lib/twingly/search/error.rb

@@ -0,0 +1,27 @@
+module Twingly
+  module Search
+    class Error < StandardError
+      # @param [String] message API response error message.
+      # @return [Error] an instance of {AuthError} or {ServerError}.
+      def self.from_api_response_message(message)
+        error =
+          if message =~ /API key/
+            AuthError
+          else
+            ServerError
+          end
+
+        error.new(message)
+      end
+    end
+
+    class AuthError < Error
+    end
+
+    class ServerError < Error
+    end
+
+    class QueryError < Error
+    end
+  end
+end

data/lib/twingly/search/parser.rb

@@ -3,29 +3,43 @@ require 'nokogiri'
 module Twingly
   module Search
     class Parser
+      # Parse an API response body.
+      #
+      # @param [String] document containing an API response XML.
+      # @raise [Error] which error depends on the API response (see {Error.from_api_response_message}).
+      # @return [Result] containing the result.
       def parse(document)
-        result = Result.new
         nokogiri = Nokogiri::XML(document)
 
-        failure = nokogiri.at_xpath('//name:blogstream/name:operationResult[@resultType="failure"]', :name => 'http://www.twingly.com')
-        fail failure.text if failure
+        failure = nokogiri.at_xpath('//name:blogstream/name:operationResult[@resultType="failure"]', name: 'http://www.twingly.com')
+        handle_failure(failure) if failure
+
+        data_node = nokogiri.at_xpath('/twinglydata')
+        handle_non_xml_document(nokogiri) unless data_node
+
+        create_result(data_node)
+      end
+
+      private
 
-        result.number_of_matches_returned = nokogiri.at_xpath('/twinglydata/@numberOfMatchesReturned').value.to_i
-        result.number_of_matches_total = nokogiri.at_xpath('/twinglydata/@numberOfMatchesTotal').value.to_i
-        result.seconds_elapsed = nokogiri.at_xpath('/twinglydata/@secondsElapsed').value.to_f
+      def create_result(data_node)
+        result = Result.new
+        result.number_of_matches_returned = data_node.attribute('numberOfMatchesReturned').value.to_i
+        result.number_of_matches_total    = data_node.attribute('numberOfMatchesTotal').value.to_i
+        result.seconds_elapsed            = data_node.attribute('secondsElapsed').value.to_f
 
-        nokogiri.xpath('//post').each do |post|
+        data_node.xpath('//post').each do |post|
           result.posts << parse_post(post)
         end
 
         result
       end
-    private
+
       def parse_post(element)
         post_params = {}
         element.element_children.each do |child|
           if child.name == 'tags'
-            post_params[child.name] = parse_tags(child) if child.name == 'tags'
+            post_params[child.name] = parse_tags(child)
           else
             post_params[child.name] = child.text
           end
@@ -40,6 +54,15 @@ module Twingly
           child.text
         end
       end
+
+      def handle_failure(failure)
+        fail Error.from_api_response_message(failure.text)
+      end
+
+      def handle_non_xml_document(document)
+        response_text = document.search('//text()').map(&:text)
+        fail ServerError, response_text
+      end
     end
   end
 end

data/lib/twingly/search/post.rb

@@ -4,10 +4,29 @@ require 'date'
 
 module Twingly
   module Search
+    # A blog post
+    #
+    # @attr_reader [String] url the post URL.
+    # @attr_reader [String] title the post title.
+    # @attr_reader [String] summary the blog post text.
+    # @attr_reader [String] language_code ISO two letter language code for the
+    #   language that the post was written in.
+    # @attr_reader [DateTime] indexed the time, in UTC, when this post was indexed by Twingly.
+    # @attr_reader [DateTime] published the time, in UTC, when this post was published.
+    # @attr_reader [String] blog_url the blog URL.
+    # @attr_reader [String] blog_name name of the blog.
+    # @attr_reader [String] authority the blog's authority/influence.
+    #   See https://developer.twingly.com/resources/search/#authority
+    # @attr_reader [Integer] blog_rank the rank of the blog, based on authority and language.
+    #   See https://developer.twingly.com/resources/search/#authority
+    # @attr_reader [Array] tags
     class Post
       attr_reader :url, :title, :summary, :language_code, :indexed,
         :published, :blog_url, :blog_name, :authority, :blog_rank, :tags
 
+      # Sets all instance variables for the {Post}, given a Hash.
+      #
+      # @param [Hash] params containing blog post data.
       def set_values(params)
         @url           = params.fetch('url')
         @title         = params.fetch('title')

data/lib/twingly/search/query.rb

@@ -1,43 +1,62 @@
-require 'faraday'
+require "faraday"
 
 module Twingly
   module Search
+    # Twingly Search API query
+    #
+    # @attr [String] pattern the search query.
+    # @attr [String] language which language to restrict the query to.
+    # @attr [Client] client the client that this query is connected to.
+    # @attr [Time, #to_time] start_time search for posts published after
+    #   this time (inclusive).
+    # @attr [Time, #to_time] end_time search for posts published before
+    #   this time (inclusive).
     class Query
       attr_accessor :pattern, :language, :client, :start_time, :end_time
 
-      BASE_URL = 'https://api.twingly.com'
-      SEARCH_PATH = '/analytics/Analytics.ashx'
-
+      # No need to call this method manually, instead use {Client#query}.
+      #
+      # @param client [Client] the client that this query should be connected to.
       def initialize(client)
         @client = client
+        yield self if block_given?
       end
 
+      # @return [String] the request url for the query.
       def url
-        "#{BASE_URL}#{SEARCH_PATH}?#{url_parameters}"
+        "#{client.endpoint_url}?#{url_parameters}"
       end
 
+      # Executes the query and returns the result.
+      #
+      # @raise [QueryError] if {#pattern} is empty.
+      # @return [Result] the result for this query.
       def execute
-        Parser.new.parse(get_response.body)
+        @client.execute_query(self)
       end
 
+      # @see #url
+      # @return [String] the query part of the request url.
       def url_parameters
         Faraday::Utils.build_query(request_parameters)
       end
 
+      # @raise [QueryError] if {#pattern} is empty.
+      # @return [Hash] the request parameters.
       def request_parameters
-        fail("Missing pattern") if pattern.to_s.empty?
+        fail QueryError, "Missing pattern" if pattern.to_s.empty?
 
         {
-          :key => client.api_key,
-          :searchpattern => pattern,
-          :documentlang => language,
-          :ts => ts,
-          :tsTo => ts_to,
-          :xmloutputversion => 2
+          key: client.api_key,
+          searchpattern: pattern,
+          documentlang: language,
+          ts: ts,
+          tsTo: ts_to,
+          xmloutputversion: 2,
         }
       end
 
-    private
+      private
 
       def ts
         start_time.to_time.strftime("%F %T") if start_time
@@ -46,15 +65,6 @@ module Twingly
       def ts_to
         end_time.to_time.strftime("%F %T") if end_time
       end
-
-      def get_response
-        connection = Faraday.new(:url => BASE_URL) do |faraday|
-          faraday.request :url_encoded
-          faraday.adapter Faraday.default_adapter
-        end
-        connection.headers[:user_agent] = "Twingly Search Ruby Client/#{VERSION}"
-        connection.get(SEARCH_PATH, request_parameters)
-      end
     end
   end
 end

data/lib/twingly/search/result.rb

@@ -1,13 +1,25 @@
 module Twingly
   module Search
+    # Represents a result from a {Query} to the Search API
+    #
+    # @see Query#execute
+    # @attr [Integer] number_of_matches_returned number of {Post}s
+    #   the {Query} returned.
+    # @attr [Integer] number_of_matches_total total number of {Post}s
+    #   the {Query} matched.
+    # @attr [Integer] seconds_elapsed number of seconds it took to
+    #   execute the {Query}.
     class Result
       attr_accessor :number_of_matches_returned, :number_of_matches_total,
         :seconds_elapsed
 
+      # @return [Array<Post>] all posts that matched the {Query}.
       def posts
         @posts ||= []
       end
 
+      # @return [true] if this result includes all {Post}s that matched the {Query}.
+      # @return [false] if there are more {Post}s to fetch from the API.
       def all_results_returned?
         number_of_matches_returned.to_i == number_of_matches_total.to_i
       end

data/lib/twingly/search/version.rb

@@ -1,5 +1,5 @@
 module Twingly
   module Search
-    VERSION = "3.0.0"
+    VERSION = "4.0.0"
   end
 end

data/spec/client_spec.rb

@@ -4,24 +4,111 @@ include Twingly::Search
 
 describe Client do
   subject { Client.new('api_key') }
-  context 'with API key as arguments' do
-    it { should be_a Client }
-  end
 
-  context 'with API key from ENV variable' do
-    before { allow_any_instance_of(Client).to receive(:env_api_key).and_return('api_key') }
-    subject { Client.new }
-    it { should be_a Client }
-  end
+  describe ".new" do
+    context 'with API key as arguments' do
+      it { should be_a Client }
+    end
+
+    it "BASE_URL should be parsable" do
+      expect(URI(Client::BASE_URL).to_s).to eq(Client::BASE_URL)
+    end
+
+    context 'with API key from ENV variable' do
+      before { allow_any_instance_of(Client).to receive(:env_api_key).and_return('api_key') }
+      subject { Client.new }
+      it { should be_a Client }
+    end
+
+    context 'without valid API key' do
+      before { allow_any_instance_of(Client).to receive(:env_api_key).and_return(nil) }
+      subject { Client.new }
+      it { expect { subject }.to raise_error(AuthError, "No API key has been provided.") }
+    end
+
+    context "with optional :user_agent given" do
+      let(:user_agent) { "TwinglySearchTest/1.0" }
+      subject { Client.new('api_key', user_agent: user_agent) }
+
+      it "should use that user agent" do
+        expect(subject.user_agent).to eq(user_agent)
+      end
+    end
+
+    context "with block" do
+      it "should yield self" do
+        yielded_client = nil
+        client = Client.new("api_key") do |c|
+          yielded_client = c
+        end
+
+        expect(yielded_client).to equal(client)
+      end
+
+      context "when api key gets set in block" do
+        before { allow_any_instance_of(Client).to receive(:env_api_key).and_return(nil) }
+        let(:api_key) { "api_key_from_block" }
+        subject do
+          Client.new do |client|
+            client.api_key = api_key
+          end
+        end
+
+        it "should not raise an AuthError" do
+          expect { subject }.not_to raise_exception
+        end
 
-  context 'without valid API key' do
-    before { allow_any_instance_of(Client).to receive(:env_api_key).and_return(nil) }
-    subject { Client.new }
-    it { expect { subject }.to raise_error(RuntimeError, 'Missing API key') }
+        it "should use that api key" do
+          expect(subject.api_key).to eq(api_key)
+        end
+      end
+    end
   end
 
   describe '#query' do
     subject { Client.new('api_key').query }
     it { should be_a Query }
+
+    context "with block" do
+      subject { Client.new("api_key") }
+
+      it "should yield the query" do
+        yielded_query = nil
+        query = subject.query do |q|
+          yielded_query = q
+        end
+
+        expect(yielded_query).to equal(query)
+      end
+    end
+  end
+
+  describe "#execute_query" do
+    context "with invalid API key" do
+      subject { Client.new("wrong") }
+
+      let(:query) do
+        query = subject.query
+        query.pattern = "something"
+        query
+      end
+
+      it "should raise error on invalid API key" do
+        VCR.use_cassette("search_without_valid_api_key") do
+          expect { subject.execute_query(query) }.to raise_error(AuthError, "The API key does not exist.")
+        end
+      end
+    end
+  end
+
+  describe "#endpoint_url" do
+    subject { Client.new("api_key").endpoint_url }
+    let(:expected) { "#{Client::BASE_URL}#{Client::SEARCH_PATH}" }
+
+    it { is_expected.to eq(expected) }
+
+    it "should be parsable" do
+      expect(URI(subject).to_s).to eq(expected)
+    end
   end
 end

data/spec/error_spec.rb

@@ -0,0 +1,35 @@
+require "spec_helper"
+
+describe Twingly::Search::Error do
+  it { is_expected.to be_a(StandardError) }
+
+  describe ".from_api_response_message" do
+    subject { described_class.from_api_response_message(server_response_message) }
+
+    context "when given message containing 'API key'" do
+      let(:server_response_message) { "... API key ..." }
+
+      it { is_expected.to be_an(AuthError) }
+    end
+
+    context "when given a server error message" do
+      let(:server_response_message) { "An error occured." }
+
+      it { is_expected.to be_an(ServerError) }
+    end
+  end
+
+  describe "all error classes" do
+    error_classes = [
+      AuthError,
+      ServerError,
+      QueryError,
+    ]
+
+    error_classes.each do |error_class|
+      describe error_class do
+        it { is_expected.to be_kind_of(Twingly::Search::Error) }
+      end
+    end
+  end
+end

data/spec/fixtures/non_xml_result.xml

@@ -0,0 +1,3 @@
+<html><body><h1>503 Service Unavailable</h1>
+No server is available to handle this request.
+</body></html>

data/spec/fixtures/service_unavailable_result.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?><blogstream xmlns="http://www.twingly.com">
+  <operationResult resultType="failure">Authentication service unavailable.</operationResult>
+</blogstream>

data/spec/fixtures/unauthorized_api_key_result.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?><blogstream xmlns="http://www.twingly.com">
+  <operationResult resultType="failure">The API key does not grant access to the Search API.</operationResult>
+</blogstream>

data/spec/fixtures/undefined_error_result.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?><blogstream xmlns="http://www.twingly.com">
+  <operationResult resultType="failure">Something went wrong.</operationResult>
+</blogstream>

data/spec/parser_spec.rb

@@ -5,10 +5,53 @@ include Twingly::Search
 describe Parser do
   it { should respond_to(:parse) }
 
-  let(:document) { File.read('spec/fixtures/valid_result.xml') }
-
   describe "#parse" do
     subject { Parser.new.parse(document) }
-    it { should be_a Result }
+
+    context "with a valid result" do
+      let(:document) { Fixture.get(:valid) }
+
+      it { is_expected.to be_a Result }
+    end
+
+    context "with a nonexistent api key result" do
+      let(:document) { Fixture.get(:nonexistent_api_key) }
+
+      it "should raise AuthError" do
+        expect { subject }.to raise_error(AuthError)
+      end
+    end
+
+    context "with an unauthorized api key result" do
+      let(:document) { Fixture.get(:unauthorized_api_key) }
+
+      it "should raise AuthError" do
+        expect { subject }.to raise_error(AuthError)
+      end
+    end
+
+    context "with a service unavailable result" do
+      let(:document) { Fixture.get(:service_unavailable) }
+
+      it "should raise ServerError" do
+        expect { subject }.to raise_error(ServerError)
+      end
+    end
+
+    context "with a undefined error result" do
+      let(:document) { Fixture.get(:undefined_error) }
+
+      it "should raise ServerError" do
+        expect { subject }.to raise_error(ServerError)
+      end
+    end
+
+    context "with a undefined error result" do
+      let(:document) { Fixture.get(:non_xml) }
+
+      it "should raise ServerError" do
+        expect { subject }.to raise_error(ServerError, /503 Service Unavailable/)
+      end
+    end
   end
 end

data/spec/query_spec.rb

@@ -4,25 +4,13 @@ require 'vcr_setup'
 include Twingly::Search
 
 describe Query do
-
-  it "BASE_URL should be parsable" do
-    expect(URI(Query::BASE_URL).to_s).to eq(Query::BASE_URL)
-  end
-
-  context "without client" do
-    subject { Query.new }
-
-    it "should not work" do
-      expect { subject }.to raise_error(ArgumentError)
-    end
-  end
+  let(:client_double) { double("Client") }
 
   before(:each) do
-    @client = double('client')
-    allow(@client).to receive(:api_key).and_return('api_key')
+    allow(client_double).to receive(:api_key).and_return("api_key")
   end
 
-  subject { Query.new(@client) }
+  subject { Query.new(client_double) }
 
   it { should respond_to(:pattern) }
   it { should respond_to(:language) }
@@ -31,8 +19,34 @@ describe Query do
   it { should respond_to(:execute) }
   it { should respond_to(:client) }
 
+  describe ".new" do
+    context "without client" do
+      subject { Query.new }
+
+      it "should not work" do
+        expect { subject }.to raise_error(ArgumentError)
+      end
+    end
+
+    context "with block" do
+      it "should yield self" do
+        yielded_query = nil
+        query = Query.new(client_double) do |q|
+          yielded_query = q
+        end
+
+        expect(yielded_query).to equal(query)
+      end
+    end
+  end
+
   describe "#url" do
-    let(:query) { Query.new(@client) }
+    before do
+      endpoint_url = "https://api.twingly.com/analytics/Analytics.ashx"
+      allow(client_double).to receive(:endpoint_url).and_return(endpoint_url)
+    end
+
+    let(:query) { Query.new(client_double) }
 
     context "with valid pattern" do
       before { query.pattern = "christmas" }
@@ -43,7 +57,7 @@ describe Query do
 
     context "without valid pattern" do
       it "raises an error" do
-        expect { query.url }.to raise_error(RuntimeError, "Missing pattern")
+        expect { query.url }.to raise_error(QueryError, "Missing pattern")
       end
     end
 
@@ -51,7 +65,7 @@ describe Query do
       before { query.pattern = "" }
 
       it "raises an error" do
-        expect { query.url }.to raise_error(RuntimeError, "Missing pattern")
+        expect { query.url }.to raise_error(QueryError, "Missing pattern")
       end
     end
   end
@@ -89,17 +103,18 @@ describe Query do
   end
 
   describe "#execute" do
-    context "with invalid API key" do
-      subject {
-        query = Query.new(Client.new('wrong'))
+    context "when called" do
+      let(:client) { instance_double("Client", "api_key") }
+      subject do
+        query = Query.new(client)
         query.pattern = 'something'
         query
-      }
+      end
 
-      it "should raise error on invalid API key" do
-        VCR.use_cassette('search_without_valid_api_key') do
-          expect { subject.execute }.to raise_error(RuntimeError, "The API key does not exist.")
-        end
+      it "should send the query to the client" do
+        expect(client).to receive(:execute_query).with(subject)
+
+        subject.execute
       end
     end
 

data/spec/spec_helper.rb

@@ -1 +1,8 @@
 require File.dirname(__FILE__) + '/../lib/twingly/search'
+
+class Fixture
+  def self.get(fixture_name)
+    filename = "spec/fixtures/#{fixture_name}_result.xml"
+    File.read(filename)
+  end
+end

data/twingly-search-api-ruby.gemspec

@@ -27,4 +27,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "webmock", "~> 1.0"
   spec.add_development_dependency "rake", "~> 0"
   spec.add_development_dependency "github_changelog_generator", "~> 1.8"
+  spec.add_development_dependency "yard", "~> 0.8"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: twingly-search
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Twingly AB
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-11-20 00:00:00.000000000 Z
+date: 2015-12-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -128,6 +128,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 description: Twingly Search is a product from Twingly AB
 email:
 - support@twingly.com
@@ -147,13 +161,19 @@ files:
 - examples/hello_world.rb
 - lib/twingly/search.rb
 - lib/twingly/search/client.rb
+- lib/twingly/search/error.rb
 - lib/twingly/search/parser.rb
 - lib/twingly/search/post.rb
 - lib/twingly/search/query.rb
 - lib/twingly/search/result.rb
 - lib/twingly/search/version.rb
 - spec/client_spec.rb
-- spec/fixtures/invalid_result.xml
+- spec/error_spec.rb
+- spec/fixtures/non_xml_result.xml
+- spec/fixtures/nonexistent_api_key_result.xml
+- spec/fixtures/service_unavailable_result.xml
+- spec/fixtures/unauthorized_api_key_result.xml
+- spec/fixtures/undefined_error_result.xml
 - spec/fixtures/valid_result.xml
 - spec/fixtures/vcr_cassettes/search_for_spotify_on_sv_blogs.yml
 - spec/fixtures/vcr_cassettes/search_without_valid_api_key.yml
@@ -184,13 +204,18 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.0
+rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
 summary: Ruby API client for Twingly Search
 test_files:
 - spec/client_spec.rb
-- spec/fixtures/invalid_result.xml
+- spec/error_spec.rb
+- spec/fixtures/non_xml_result.xml
+- spec/fixtures/nonexistent_api_key_result.xml
+- spec/fixtures/service_unavailable_result.xml
+- spec/fixtures/unauthorized_api_key_result.xml
+- spec/fixtures/undefined_error_result.xml
 - spec/fixtures/valid_result.xml
 - spec/fixtures/vcr_cassettes/search_for_spotify_on_sv_blogs.yml
 - spec/fixtures/vcr_cassettes/search_without_valid_api_key.yml
@@ -200,3 +225,4 @@ test_files:
 - spec/result_spec.rb
 - spec/spec_helper.rb
 - spec/vcr_setup.rb
+has_rdoc: