twingly-search 3.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4a32c03b5a124011f9486d4724a9390f74fd88f2
+  data.tar.gz: b7c26d1ba53842a58e40f25ae54abbe9c0dee8f7
+SHA512:
+  metadata.gz: 5a3ffe5d6257cb17d9e32df29cac7e9014829b99d71aef1c0adef5cae4d338018dcbc378af4d5b4d299753851fac6c4b10c24e38ebea8e23a950647d8c250134
+  data.tar.gz: 9142bf21df1a9655f89c4df65ab3072a2bf7e3efc054cec70cb332ea7c37a83fb29d7442b77d40707e8843512d2c51fe5dfdde5b3741c8675aff8aa7fee258da

data/.gitignore

@@ -0,0 +1,4 @@
+.env
+Gemfile.lock
+.ruby-version
+*.gem

data/.travis.yml

@@ -0,0 +1,27 @@
+language: ruby
+cache: bundler
+rvm:
+- 1.9.3
+- 2.0.0
+- 2.1
+- 2.2
+deploy:
+  provider: rubygems
+  api_key:
+    secure: QxMWXTQ3/T+0IQZl3pk3hmdoX8FcXTXEhH7Jn7Ub1A1D5faa8VNnfYsWAPjP6+VRgVfKEjAsHNMyZQNTvudpPPC/2kAwwzPvStyS+y7KnRkjZ9acC7sYVVel6cZ2lcl+t8iHY+19NRBFBWpq/P0eCAcR/Ew0XXaLZnig5h/1mQo=
+  gem: twingly-search
+  gemspec: twingly-search-api-ruby.gemspec
+  on:
+    tags: true
+    rvm: 2.2
+    repo: twingly/twingly-search-api-ruby
+notifications:
+  email: false
+  hipchat:
+    on_success: never
+    on_failure: change
+    template:
+    - '%{repository}#%{build_number} (%{branch} - %{commit} : %{author}): %{message} (<a href="%{build_url}">Details</a>/<a href="%{compare_url}">Change view</a>)'
+    format: html
+    rooms:
+      secure: KU2mE9mcqvBczfiCTgTsgMmJPyW02AH/0Rzcli7oj3HVbiHGw8t5JlBQWYROF5TPht0kFhGkiwVPl6HUt/VAGxOIBsOp+/8MXR6aK5FkdIw6g8DMKlDjm9a2QijOT9rvat5bZ3l6hm3snojgkI3s9pLKmLq9l+KalAsPcevwKAQ=

data/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Change Log
+
+## [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)
+
+**Fixed bugs:**
+
+- Crash when pattern is empty string [\#17](https://github.com/twingly/twingly-search-api-ruby/issues/17)
+
+**Merged pull requests:**
+
+- Do not allow empty search pattern [\#18](https://github.com/twingly/twingly-search-api-ruby/pull/18) ([twingly-mob](https://github.com/twingly-mob))
+- Generate Changelog \(with instructions to update it\) [\#16](https://github.com/twingly/twingly-search-api-ruby/pull/16) ([jage](https://github.com/jage))
+
+## [2.0.0](https://github.com/twingly/twingly-search-api-ruby/tree/2.0.0) (2015-09-14)
+[Full Changelog](https://github.com/twingly/twingly-search-api-ruby/compare/1.0.1...2.0.0)
+
+**Implemented enhancements:**
+
+- Release gem to rubygems.org [\#10](https://github.com/twingly/twingly-search-api-ruby/issues/10)
+
+**Merged pull requests:**
+
+- Improve time pagination \(breaking compatibility for Query\#start\_time and Query\#end\_time\) [\#15](https://github.com/twingly/twingly-search-api-ruby/pull/15) ([jage](https://github.com/jage))
+
+## [1.0.1](https://github.com/twingly/twingly-search-api-ruby/tree/1.0.1) (2015-04-29)
+[Full Changelog](https://github.com/twingly/twingly-search-api-ruby/compare/1.0.0...1.0.1)
+
+**Fixed bugs:**
+
+- Support Ruby 2.2 [\#12](https://github.com/twingly/twingly-search-api-ruby/issues/12)
+- HTTPS broke compatibility with Ruby 1.9.3 [\#8](https://github.com/twingly/twingly-search-api-ruby/issues/8)
+
+**Closed issues:**
+
+- Use the rspec-its gem [\#11](https://github.com/twingly/twingly-search-api-ruby/issues/11)
+
+**Merged pull requests:**
+
+- Fix deprecations [\#14](https://github.com/twingly/twingly-search-api-ruby/pull/14) ([walro](https://github.com/walro))
+- Support Ruby 2.2 [\#13](https://github.com/twingly/twingly-search-api-ruby/pull/13) ([dentarg](https://github.com/dentarg))
+- Use Faraday instead of Net::HTTP directly [\#9](https://github.com/twingly/twingly-search-api-ruby/pull/9) ([jage](https://github.com/jage))
+
+## [1.0.0](https://github.com/twingly/twingly-search-api-ruby/tree/1.0.0) (2014-10-30)
+**Implemented enhancements:**
+
+- Use HTTPS for API access [\#7](https://github.com/twingly/twingly-search-api-ruby/issues/7)
+- Remove swedish comment [\#5](https://github.com/twingly/twingly-search-api-ruby/issues/5)
+- Rewrite history to remove huge vcr-cassettes [\#4](https://github.com/twingly/twingly-search-api-ruby/issues/4)
+- Remove humongous vcr cassettes [\#1](https://github.com/twingly/twingly-search-api-ruby/issues/1)
+
+**Closed issues:**
+
+- Add a LICENSE [\#6](https://github.com/twingly/twingly-search-api-ruby/issues/6)
+- Wrap lines at 72 characters [\#2](https://github.com/twingly/twingly-search-api-ruby/issues/2)
+
+**Merged pull requests:**
+
+- Refactor to improve readability [\#3](https://github.com/twingly/twingly-search-api-ruby/pull/3) ([jage](https://github.com/jage))
+
+
+
+\* *This Change Log was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org/'
+
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Twingly AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,77 @@
+# 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)
+
+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/).
+
+## Installation
+
+Install via RubyGems
+
+```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'
+```
+
+## Usage
+
+```Ruby
+require 'twingly/search'
+
+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
+```
+
+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/).
+
+Too learn more about the capabilities of this API you should read the [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
+
+## Development and release
+
+1. Make sure the master branch has an up-to-date changelog. Generate with `rake changelog`. Set `CHANGELOG_GITHUB_TOKEN` to a personal access token to increase the API rate limit. (The changelog uses [GitHub Changelog Generator](https://github.com/skywinder/github-changelog-generator/))
+1. Bump version in `lib/twingly/search/version.rb`, follow [Semantic Versioning 2.0.0](http://semver.org/)
+1. Build and release gem with `bundle exec rake release`. This will create a git tag for the version and push the `.gem` file to https://rubygems.org/.
+1. Update release information on the [releases page].
+
+[releases page]: https://github.com/twingly/twingly-search-api-ruby/releases
+
+## License
+
+The MIT License (MIT)
+
+Copyright (c) 2013 Twingly AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,23 @@
+require "rake"
+require "bundler/setup"
+require "bundler/gem_tasks"
+
+desc "Run specs"
+task :spec do
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new(:spec) do |t|
+    t.rspec_opts = %w(-fd -c)
+  end
+end
+
+require "github_changelog_generator/task"
+GitHubChangelogGenerator::RakeTask.new(:changelog) do |config|
+  config.user = "twingly"
+  config.project = "twingly-search-api-ruby"
+end
+
+desc "Synonym for spec"
+task :test => :spec
+desc "Synonym for spec"
+task :tests => :spec
+task :default => :spec

data/examples/Gemfile

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

data/examples/find_all_posts_mentioning_github.rb

@@ -0,0 +1,29 @@
+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}"
+  end
+
+  def each
+    loop do
+      result = @query.execute
+      result.posts.each do |post|
+        yield post
+      end
+
+      break if result.all_results_returned?
+
+      @query.start_time = result.posts.last.published
+    end
+  end
+end
+
+stream = SearchPostStream.new("(github) AND (hipchat OR slack)")
+stream.each do |post|
+  puts post.url
+end

data/examples/hello_world.rb

@@ -0,0 +1,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
+result = query.execute
+result.posts.each do |post|
+  puts post.url
+end

data/lib/twingly/search.rb

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,19 @@
+module Twingly
+  module Search
+    class Client
+      attr_accessor :api_key
+
+      def initialize(api_key = nil)
+        @api_key = api_key || env_api_key || fail("Missing API key")
+      end
+
+      def query
+        Query.new(self)
+      end
+    private
+      def env_api_key
+        ENV['TWINGLY_SEARCH_KEY']
+      end
+    end
+  end
+end

data/lib/twingly/search/parser.rb

@@ -0,0 +1,45 @@
+require 'nokogiri'
+
+module Twingly
+  module Search
+    class Parser
+      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
+
+        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
+
+        nokogiri.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'
+          else
+            post_params[child.name] = child.text
+          end
+        end
+        post = Post.new
+        post.set_values(post_params)
+        post
+      end
+
+      def parse_tags(element)
+        element.element_children.map do |child|
+          child.text
+        end
+      end
+    end
+  end
+end

data/lib/twingly/search/post.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+require 'date'
+
+module Twingly
+  module Search
+    class Post
+      attr_reader :url, :title, :summary, :language_code, :indexed,
+        :published, :blog_url, :blog_name, :authority, :blog_rank, :tags
+
+      def set_values(params)
+        @url           = params.fetch('url')
+        @title         = params.fetch('title')
+        @summary       = params.fetch('summary')
+        @language_code = params.fetch('languageCode')
+        @published     = DateTime.parse(params.fetch('published'))
+        @indexed       = DateTime.parse(params.fetch('indexed'))
+        @blog_url      = params.fetch('blogUrl')
+        @blog_name     = params.fetch('blogName')
+        @authority     = params.fetch('authority').to_i
+        @blog_rank     = params.fetch('blogRank').to_i
+        @tags          = params.fetch('tags', [])
+      end
+    end
+  end
+end

data/lib/twingly/search/query.rb

@@ -0,0 +1,60 @@
+require 'faraday'
+
+module Twingly
+  module Search
+    class Query
+      attr_accessor :pattern, :language, :client, :start_time, :end_time
+
+      BASE_URL = 'https://api.twingly.com'
+      SEARCH_PATH = '/analytics/Analytics.ashx'
+
+      def initialize(client)
+        @client = client
+      end
+
+      def url
+        "#{BASE_URL}#{SEARCH_PATH}?#{url_parameters}"
+      end
+
+      def execute
+        Parser.new.parse(get_response.body)
+      end
+
+      def url_parameters
+        Faraday::Utils.build_query(request_parameters)
+      end
+
+      def request_parameters
+        fail("Missing pattern") if pattern.to_s.empty?
+
+        {
+          :key => client.api_key,
+          :searchpattern => pattern,
+          :documentlang => language,
+          :ts => ts,
+          :tsTo => ts_to,
+          :xmloutputversion => 2
+        }
+      end
+
+    private
+
+      def ts
+        start_time.to_time.strftime("%F %T") if start_time
+      end
+
+      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