threetaps-client 0.5.1

data/Gemfile

@@ -0,0 +1,17 @@
+source "http://rubygems.org"
+gem "supermodel", "~> 0.1.4"
+gem "curb", "~> 0.7.9"
+gem "activesupport", "~> 3.0.0"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "rcov", ">= 0"
+  gem "rspec"
+end

data/Gemfile.lock

@@ -0,0 +1,43 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      i18n (~> 0.4)
+    activesupport (3.0.3)
+    builder (2.1.2)
+    curb (0.7.12)
+    diff-lcs (1.1.2)
+    git (1.2.5)
+    i18n (0.5.0)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+    rcov (0.9.9)
+    rspec (2.3.0)
+      rspec-core (~> 2.3.0)
+      rspec-expectations (~> 2.3.0)
+      rspec-mocks (~> 2.3.0)
+    rspec-core (2.3.1)
+    rspec-expectations (2.3.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.3.0)
+    shoulda (2.11.3)
+    supermodel (0.1.4)
+      activemodel (>= 3.0.0.beta)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (~> 3.0.0)
+  bundler (~> 1.0.0)
+  curb (~> 0.7.9)
+  jeweler (~> 1.5.2)
+  rcov
+  rspec
+  shoulda
+  supermodel (~> 0.1.4)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 marat
+
+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.rdoc

@@ -0,0 +1,48 @@
+= threetaps-client
+
+== Installation
+
+== Usage
+
+=== Search
+
+To perform a search you need to
+1. create SearchRequest object and fill its attributes
+
+   request = SearchRequest.new
+
+   request.rpp = 10
+
+   request.text = "porsche"
+
+2. create SearchClient object
+
+   client = SearchClient.new
+
+3. call search method on client with request as a parameter and get an SearchResponse object.
+
+   response = client.search(request)
+
+4. now you can operate with search results:
+
+   postings = response.results
+
+   quantity = response.num_results
+
+   execution_time = response.exec_time_ms
+
+== Contributing to threetaps-client
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so we don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 3taps.com. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,68 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "threetaps-client"
+  gem.homepage = "https://github.com/3taps/3taps-Ruby-Client"
+  gem.license = "MIT"
+  gem.summary = %Q{A Ruby gem for accessing the 3taps API}
+  gem.description = %Q{A Ruby gem for accessing the 3taps API. See more at http://developers.3taps.net}
+  gem.email = "developers@3taps.com"
+  gem.authors = ["3taps.com"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.rspec_opts = ['--color']
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+# Run the unit tests
+desc "Run all unit tests"
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new(:rcovtest) do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "threetaps-client #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.5.1

data/lib/client/client.rb

@@ -0,0 +1,43 @@
+# Base class for 3taps API client classes.
+class Client
+  DEFAULT_URL = 'http://3taps.net'
+  DEFAULT_API_PORT = 80
+  # Initializes Client class with +baseUrl+ and +port+ parameters. By default 
+  # DEFAULT_URL and DEFAULT_API_PORT are used. Examples:
+  #  Client.new
+  #  Client.new("http://3taps.com", 8080)
+  def initialize(baseUrl = DEFAULT_URL, port = DEFAULT_API_PORT)
+    @baseURL = baseUrl
+    @port = port
+  end
+
+  # Executes GET request on URL and port with +path+ and +params+ parameters.
+  # Example:
+  #
+  #  execute_get("/search", "data=data")
+  def execute_get( path, params = nil )
+    address = params.nil? ? path : path + '?' + params 
+    request = Curl::Easy.new("#{@baseURL}:#{@port}" + address) 
+    begin
+      request.perform
+    rescue
+      "Some Error with Request."
+    end
+    request.body_str
+  end
+
+  # Executes POST request on URL and port with +path+ and +params+ parameters.
+  # Example:
+  #
+  #  execute_post("search", "data=data")
+  def execute_post( path, params = nil )
+    c = Curl::Easy.http_post("#{@baseURL}:#{@port}/#{path}", params)
+    c.body_str
+  end
+
+  private
+
+  def decode(data)
+    ActiveSupport::JSON.decode(data)
+  end
+end

data/lib/client/geocoder_client.rb

@@ -0,0 +1,42 @@
+# Class GeocoderClient represents server request of geocoding API (calculate
+# the location to use for a posting based on location-specific details within
+# the posting such as a street address or a latitude and longitude value).
+#
+# Its methods are used to query API with appropriate requests:
+# geocode(requests) - returns array of responses
+#
+# Example:
+#
+#  client = GeocoderClient.new
+#  request = GeocoderRequest.new
+#  request.latitude = '37.77493'
+#  request.longitude = '-122.41942'
+#
+#  response = client.geocode(request)
+#
+#  response.first.code       # => "CAZ"
+#  response.first.latitude   # => 39.77493
+#  response.first.longitude  # => -122.41942
+
+class GeocoderClient < Client
+
+  # Method geocode sends geocode request to Geocode API.
+  # Takes array of GeocoderRequest objects as +requests+ parameter.
+  #
+  # Examples:
+  #
+  #  request = GeocoderRequest.new
+  #  client.geocode(request) # => [GeocoderResponse]
+  #
+  #  requests = [GeocoderRequest.new, GeocoderRequest.new]
+  #  client.geocode(requests) # => [GeocoderResponse, GeocoderResponse]
+  #
+  def geocode(geocoder_requests)
+    geocoder_requests = [geocoder_requests] unless geocoder_requests.is_a? Array
+    params = "data=["
+    params << geocoder_requests.collect{|request| "#{request.to_params}"}.join(',')
+    params << "]"
+    response = execute_post('geocoder/geocode', params)
+    GeocoderResponse.from_array(decode(response))
+  end
+end

data/lib/client/posting_client.rb

@@ -0,0 +1,88 @@
+# The PostingClient class allows clients to use 3taps Posting API to store and
+# retrieve postings in the 3taps system.
+#
+# Its methods are used to query API with appropriate requests:
+#  client = PostingClient.new
+#  client.get_posting(post_key)      # => returns a single Posting object
+#  client.create_posting(postings)   # => returns array of CreateResponse objects
+#  client.update_posting(postings)   # => returns array of UpdateResponse objects
+#  client.delete_posting(post_keys)  # => returns array of DeleteResponse objects
+#  client.exists_posting(posting)    # => returns array of ExistsResponse objects
+class PostingClient < Client
+
+  # Retrieves an information about a single posting.
+  # 
+  # Example
+  #  client = PostingClient.new
+  #  client.get_posting("...postKey string...") => Posting object
+  #
+  def get_posting(post_key)
+    response = execute_get("/posting/get/" + post_key)
+    Posting.new(decode(response))
+  end
+
+  # Method +create_posting+ saves a single new posting and multiple new postings in 3taps.
+  #
+  # Examples
+  #  client = PostingClient.new
+  #  client.update_posting([posting1, posting2])  #=> Array of CreateResponse objects
+  #
+  #  client = PostingClient.new
+  #  client.update_posting(posting2)  #=> Array with single CreateResponse object
+  #
+  def create_posting(postings)
+    postings = [postings] unless postings.is_a? Array
+    data = "["
+    data << postings.collect{|posting| posting.to_json}.join(',')
+    data << "]"
+    params = "posts=#{data}"
+    response = execute_post("/posting/create", params)
+    CreateResponse.from_array(decode(response))
+  end
+
+  # Method +update_posting+ updates  a single posting and multiple postings on 3taps.
+  #
+  # Examples:
+  #  client = PostingClient.new
+  #  client.update_posting([posting1, posting2])  #=> Array of UpdateResponse objects
+  #
+  #  client = PostingClient.new
+  #  client.update_posting(posting)  #=> Array with single UpdateResponse object
+  #
+  def update_posting(postings)
+    postings = [postings] unless postings.is_a? Array
+    data = "["
+    data << postings.collect{|posting| posting.to_json_for_update}.join(',')
+    data << "]"
+    params = "data=#{data}"
+    response = execute_post("posting/update", params)
+    UpdateResponse.from_hash(decode(response))
+  end
+
+  # Method +delete_posting+  deletes a single posting and multiple postings from 3taps.
+  # 
+  # Examples:
+  #  client = PostingClient.new
+  #  response = client.delete_posting(...Array of postKeys strings...)     # => Array of DeleteResponse objects
+  #
+  #  client = PostingClient.new
+  #  key = some_posting.postKey
+  #  response = client.delete_posting(key)     # => Array with single DeleteResponse object
+  #
+  def delete_posting(post_keys)
+    post_keys = [post_keys] unless post_keys.is_a? Array
+    params = "data=['#{post_keys.join("','")}']"
+    response = execute_post("posting/delete", params)
+    DeleteResponse.from_hash(decode(response))
+  end
+
+  # NOT USED
+  #
+  #  Returns information on the existence of postings.
+  #
+  def exists_posting(posting)
+    params = "ids=#{posting}"
+    response = execute_post("/posting/exists", params)
+    ExistsResponse.from_array(decode(response))
+  end
+end

data/lib/client/reference_client.rb

@@ -0,0 +1,60 @@
+# Class ReferenceClient represents server request of reference API (provides a
+# mechanism for accessing the standard "reference information" used by the
+# 3taps system, including locations, categories, and sources).
+#
+# Its methods are used to query API with appropriate requests:
+#  client = ReferenceClient.new
+#  client.get_categories     # => returns array of Category objects
+#  client.get_category(code) # => returns Category object
+#  client.get_locations      # => returns array of Location objects
+#  client.get_sources        # => returns array of Source objects
+
+class ReferenceClient < Client
+
+  # Method +get_categories+ returns the 3taps categories.
+  #
+  # Example:
+  #
+  #  client = ReferenceClient.new
+  #  client.get_categories # => Array of Category
+  #
+  def get_categories
+    response = execute_get("/reference/category")
+    File.new("newfile",  "w+") << response
+    Category.from_array(decode(response))
+  end
+
+  # Method +get_category+ returns a single category by passing in the category code.
+  # Takes value of code objects as +String+ parameter.
+  # 
+  # Example:
+  #
+  #  client.get_category('NYC') # => Categoty
+  #
+  def get_category(code)
+    response = execute_get("/reference/category/" + code)
+    Category.from_hash(decode(response)[0])
+  end
+
+  # Method +get_locations+ returns the 3taps locations.
+  #
+  # Example:
+  #
+  #  client.get_locations # => Array of Location
+  #
+  def get_locations
+    response = execute_get("/reference/location")
+    Location.from_array(decode(response))
+  end
+
+  # Method +get_sources+ returns the 3taps sources.
+  #
+  # Example:
+  #
+  #  client.get_sources # => Array of Source
+  #
+  def get_sources
+    response = execute_get("/reference/source")
+    Source.from_array(decode(response))
+  end
+end

data/lib/client/search_client.rb

@@ -0,0 +1,82 @@
+# The SearchClient class allows clients to query 3taps Search API for data,
+# and data about data.
+#
+# Its methods are used to query API with appropriate requests:
+#  client = SearchClient.new
+#  client.search(search_request)    # => returns array of SearchResponse objects
+#  client.range(range_request)      # => returns array of RangeResponse objects
+#  client.summary(summary_request)  # => returns array of SummaryResponse objects
+#  client.count(search_request)     # => returns array of CountResponse objects
+#  client.best_match(keywords)      # => returns array of BestMatchResponse objects
+class SearchClient < Client
+
+  # Method +search+ searches 3taps for postings. Example:
+  #
+  #  request = SearchRequest.new
+  #  client = SearchClient.new
+  #  client.search(request)     # => SearchResponse
+  #
+  def search(search_request)
+    response = execute_get("/search", search_request.query_params)
+    SearchResponse.new(decode(response))
+  end
+
+  # Method +range+ returns the minium and maximum values currently in 3taps for
+  # the given fields that match the given Common Search Criteria inside of the
+  # RangeResponse object. The purpose of the range method is to provide
+  # developers with sensible values for range-based UI filters.
+  #
+  # Examples:
+  #
+  #  request = RangeRequest.new
+  #  client = SearchClient.new(request)
+  #  client.range(request)        # => RangeResponse
+  #
+  def range(range_request)
+    response = execute_get("/search/range", range_request.query_params)
+    RangeResponse.from_array(decode(response))
+  end
+
+  # Method +summary+ returns the total number of postings found in 3taps, across
+  # the given dimension, that match the given Common Search Criteria parameters
+  # inside of the SummaryResponse object. Searching for "text=toyota" across
+  # "dimension=source" would return a list of all sources in 3taps, along with
+  # the number of postings matching the search "text=toyota" in that source.
+  # You may currently search across dimensions source, category, and location.
+  #
+  # Examples:
+  #
+  #  request = SummaryRequest.new
+  #  client = SearchClient.new
+  #  client.summary(request)      # => SummaryResponse
+  #
+  def summary(summary_request)
+    response = execute_get("/search/summary", summary_request.query_params)
+    SummaryResponse.from_hash(decode(response))
+  end
+
+  # Method +count+ returns the total number of postings that match the given
+  # Common Search Criteria represented by SearchRequest. Example:
+  #
+  #  request = SearchRequest.new
+  #  client = SearchClient.new
+  #  client.count(request)      # => CountResponse
+  #
+  def count(search_request)
+    response = execute_get("/search/count", search_request.query_params)
+    CountResponse.new(decode(response))
+  end
+
+  # Method +best_match+ returns the 3taps category associated with the keywords,
+  # along with the number of postings in that category. Example:
+  #
+  #  keywords = "iPad,Apple,iPhone"
+  #  client = SearchClient.new
+  #  client.best_match(keywords)     # => BestMatchResponse
+  # 
+  def best_match(keywords)
+    response = execute_get("/search/best-match", "keywords=#{keywords}")
+    BestMatchResponse.from_hash(decode(response))
+  end
+
+end

data/lib/client/status_client.rb

@@ -0,0 +1,72 @@
+# The StatusClient class provides access to the Status API.
+#
+# The Status API provides access to the status of postings, both inside and
+# outside of the 3taps system. The Status API is built upon the assumption that
+# most postings can be globally identified using two pieces of data: the source
+# and the externalID. Since we can globally identify a posting, we can share the
+# status of postings between various systems.
+#
+# For example, if a posting has been
+# "sent" to the Posting API by an external source, that external source can
+# optionally send a status of "sent" to the Status API. Once the Posting API has
+# processed and saved the posting, it can send the status of "saved" to the
+# Status API. Later, if somebody looks up the posting in the Status API, they
+# will see both of these events (sent and saved), along with the time that they
+# occurred, and any relevant attributes (postKey, errors, etc). Having this
+# information available allows 3taps and sources to provide maximum visibility
+# into their processes so that both can improve data yield.
+#
+# Class StatusClient provides access to the status API of postings
+# server response returns the status of postings, if a posting has been "sent" to the Posting API by an 
+# external source, that external source can optionally send a status of "sent" the Status API.
+#
+# Its methods are used to query API with appropriate requests:
+#  client = StatusClient .new
+#  client.update_status(postings)    # => returns Message
+#  client.get_status(postings)       # => returns array of GetStatusResponse objects
+#  client.system_status              # => returns Message
+#
+class StatusClient < Client
+  #
+  # Method +update_status+ send in status events for postings. Example:
+  #
+  #  client = StatusClient.new
+  #  request = StatusUpdateRequest.new
+  #  client.update_status(request)             # => Message
+  #
+  def update_status(postings)
+    postings = [postings] unless postings.is_a? Array
+    params ='events=['
+    params << postings.collect{|posting| "{#{posting.status.to_params}, #{posting.to_json_for_status_client}}" unless posting.status.event.empty?}.join(',')
+    params << "]"
+    response = execute_post("status/update", params)
+    Message.from_hash(decode(response))
+  end
+  #
+  # Method +get_status+ get status history for postings. Example:
+  #
+  #  client = SearchClient.new
+  #  postings = Posting.new
+  #  response = client.get_status(postings)    # => Array of GetStatusResponse 
+  #
+  def get_status(postings)
+    postings = [postings] unless postings.is_a? Array
+    data = "["
+    data << postings.collect{|posting| "{#{posting.to_json_for_status_client}}"}.join(',')
+    data << "]"
+    params = "ids=#{data}"
+    response = execute_post("status/get", params)
+    GetStatusResponse.from_array(decode(response))
+  end
+  #
+  # Method +system_status+ get the current system status. Example:
+  #
+  #  client = StatusClient.new
+  #  response = client.system_status           # => Message
+  #
+  def system_status
+    response = execute_get("/status/system")
+    Message.from_hash(decode(response))
+  end
+
+end

data/lib/dto/geocoder/geocoder_request.rb

@@ -0,0 +1,16 @@
+class GeocoderRequest < Struct.new(:latitude, :longitude, :country, :state, :city, :locality, :postal, :text)
+
+  def to_params
+    result = []
+    result << "\"latitude\":#{CGI.escape latitude}" unless latitude.nil?
+    result << "\"longitude\":#{CGI.escape longitude}" unless longitude.nil?
+    result << "\"country\":\"#{CGI.escape country}\"" unless country.nil?
+    result << "\"state\":\"#{CGI.escape state}\"" unless state.nil?
+    result << "\"city\":\"#{CGI.escape city}\"" unless city.nil?
+    result << "\"locality\":\"#{CGI.escape locality}\"" unless locality.nil?
+    result << "\"postal\":\"#{CGI.escape postal}\"" unless postal.nil?
+    result << "\"tex\":\"#{CGI.escape text}\"" unless text.nil?
+    '{' + result.join(", ") + '}'
+  end
+
+end

data/lib/dto/geocoder/geocoder_response.rb

@@ -0,0 +1,7 @@
+class GeocoderResponse < Struct.new(:code, :latitude, :longitude)
+  def self.from_array(array)
+     array.collect do |geocode|
+      from_hash(:code => geocode[0], :latitude => geocode[1], :longitude => geocode[2])
+    end
+  end
+end

data/lib/dto/posting/create_response.rb

@@ -0,0 +1,23 @@
+# Class CreateResponse represents server response on +create+ Posting API
+# request. Server response is sent to +from_array+ method which creates objects
+# with attributes +postKey+, +error+ accessible via getters:
+#
+#  response = RangeResponse.from_array(...)
+#  response.postKey     # => String
+#  response.post_key    # => String
+#  response.error       # => String
+#
+class CreateResponse < Struct.new(:postKey, :error) do
+    def post_key
+      postKey
+    end
+  end
+
+  # Method +from_array+ creates an array of CreateResponse objects from a given
+  # array of JSON hashes.
+  def self.from_array(array)
+    array.collect do |element|
+      CreateResponse.new(element)
+    end
+  end
+end

data/lib/dto/posting/delete_response.rb

@@ -0,0 +1,9 @@
+# Class DeleteResponse represents server response on +delete+ Posting API
+# request. Server response is sent to +from_hash+ method which creates object
+# with attribute +success+ accessible via getter:
+#
+#  response = DeleteResponse.from_hash("success" => "true")
+#  response.success       # => true
+#
+class DeleteResponse < Struct.new(:success)
+end

data/lib/dto/posting/exists_response.rb

@@ -0,0 +1,16 @@
+# NOT USED
+#
+# Class ExistsResponse represents server response on +exists+ Posting API
+# request. Server response is sent to +from_hash+ method which creates object
+# with attribute +success+ accessible via getter:
+#
+#  response = ExistsResponse.from_hash("success" => "true")
+#  response.success       # => true
+#
+class ExistsResponse
+  attr_accessor :exists, :postKey, :error
+
+  def self.from_array(json)
+    json
+  end
+end

data/lib/dto/posting/update_response.rb

@@ -0,0 +1,9 @@
+# Class UpdateResponse represents server response on +update+ Posting API
+# request. Server response is sent to +from_hash+ method which creates object
+# with attribute +success+ accessible via getter:
+#
+#  response = UpdateResponse.from_hash("success" => "true")
+#  response.success       # => true
+#
+class UpdateResponse < Struct.new(:success)
+end