geoloqi 0.9.33 → 0.9.35

data/lib/geoloqi/session.rb

@@ -1,6 +1,26 @@
 module Geoloqi
+  # This class is used to instantiate a session object. It is designed to be thread safe, and multiple sessions can be used simultaneously,
+  # allowing for one ruby application to potentially handle multiple Geoloqi applications.
+  #
+  # @example
+  #  # Instantiate a session with your access token (obtained from the Geoloqi Developers Site):
+  #  session = Geoloqi::Session.new :access_token => 'YOUR ACCESS TOKEN'
+  #
+  #  # Instantiate a session with a custom config:
+  #  session = Geoloqi::Session.new :access_token => 'YOUR ACCESS TOKEN', :config => {:use_hashie_mash => true}
+  #
+  #  # Instantiate a session with OAuth2 credentials (obtained from the Geoloqi Developers Site):
+  #  session = Geoloqi::Session.new :config => {:client_id => 'CLIENT ID', :client_secret => 'CLIENT SECRET'}
+  #
+  #  # Get profile:
+  #  result = session.get 'account/profile'
   class Session
+    # This is the auth Hash, which is provided by the OAuth2 response. This can be stored externally and used to re-initialize the session.
+    # @return [Hash]
     attr_reader :auth
+    
+    # This is the config object attached to this session. It is unique to this session.
+    # @return [Geoloqi::Config]
     attr_accessor :config
 
     def initialize(opts={})
@@ -9,7 +29,7 @@ module Geoloqi
       self.auth = opts[:auth] || {}
       self.auth[:access_token] = opts[:access_token] if opts[:access_token]
 
-      @connection = Faraday.new(:url => Geoloqi.api_url) do |builder|
+      @connection = Faraday.new(:url => Geoloqi.api_url, :ssl => {:verify => true, :ca_file => Geoloqi::SSL_CERT_FILE}) do |builder|
         builder.adapter  @config.adapter || :net_http
       end
     end
@@ -18,47 +38,93 @@ module Geoloqi
       @auth = hash.inject({}){|memo,(k,v)| memo[k.to_sym] = v; memo}
     end
 
+    # The access token for this session.
+    # @return [String]
     def access_token
       @auth[:access_token]
     end
 
+    # Determines if the access token exists.
+    # @return [Boolean]
     def access_token?
       !access_token.nil?
     end
 
+    # The authorize url for this session.
+    #
+    # @return [String]
     def authorize_url(redirect_uri=@config.redirect_uri, opts={})
       Geoloqi.authorize_url @config.client_id, redirect_uri, opts
     end
 
+    # Makes a GET request to the Geoloqi API server and returns response.
+    #
+    # @param [String] path
+    #   Path to the resource being requested (example: '/account/profile').
+    #
+    # @param [String, Hash] query (optional)
+    #   A query string or Hash to be appended to the request.
+    #
+    # @param [Hash] headers (optional)
+    #   Adds and overwrites headers in request sent to server.
+    #
+    # @return [Hash] by default, [Hashie::Mash] if enabled in config.
+    # @example
+    #  # Get your user profile
+    #  response = session.get 'YOUR ACCESS TOKEN', 'account/profile'
+    #
+    #  # Get the last 5 locations
+    #  response = session.get 'YOUR ACCESS TOKEN', 'account/profile', :count => 5
     def get(path, query=nil, headers={})
       run :get, path, query, headers
     end
 
+    # Makes a POST request to the Geoloqi API server and returns response.
+    #
+    # @param [String] path
+    #   Path to the resource being requested (example: '/account/profile').
+    #
+    # @param [String, Hash] query (optional)
+    #   A query string or Hash to be converted to POST parameters.
+    #
+    # @param [Hash] headers (optional)
+    #   Adds and overwrites headers in request sent to server.
+    #
+    # @return [Hash] by default, [Hashie::Mash] if enabled in config.
+    # @example
+    #  # Create a new layer
+    #  Geoloqi.post 'YOUR ACCESS TOKEN', 'layer/create', :name => 'Portland Food Carts'
     def post(path, query=nil, headers={})
       run :post, path, query, headers
     end
 
+    # Makes a one-time request to the Geoloqi API server.
+    # 
+    # @return [Hash] by default, [Hashie::Mash] if enabled in config.
+    # @example
+    #  # Create a new layer
+    #  session.post 'YOUR ACCESS TOKEN', 'layer/create', :name => 'Northeast Portland'
     def run(meth, path, query=nil, headers={})
       renew_access_token! if auth[:expires_at] && Time.rfc2822(auth[:expires_at]) <= Time.now && !(path =~ /^\/?oauth\/token$/)
       retry_attempt = 0
 
       begin
         response = execute meth, path, query, headers
-        hash = JSON.parse response.body
+        hash = JSON.parse response.body, :symbolize_names => @config.symbolize_names
 
-        if hash.is_a?(Hash) && hash['error'] && @config.throw_exceptions
-          if @config.use_dynamic_exceptions && !hash['error'].nil? && !hash['error'].empty?
-            exception_class_name = hash['error'].gsub(/\W+/, '_').split('_').collect {|w| w.capitalize}.join+'Error'
+        if hash.is_a?(Hash) && hash[:error] && @config.throw_exceptions
+          if @config.use_dynamic_exceptions && !hash[:error].nil? && !hash[:error].empty?
+            exception_class_name = hash[:error].gsub(/\W+/, '_').split('_').collect {|w| w.capitalize}.join+'Error'
             Geoloqi.const_set exception_class_name, Class.new(Geoloqi::ApiError) unless Geoloqi.const_defined? exception_class_name
             raise_class = Geoloqi.const_get exception_class_name
           else
             raise_class = ApiError
           end
-          raise raise_class.new(response.status, hash['error'], hash['error_description'])
+          raise raise_class.new(response.status, hash[:error], hash[:error_description])
         end
       rescue Geoloqi::ApiError
         raise Error.new('Unable to procure fresh access token from API on second attempt') if retry_attempt > 0
-        if hash['error'] == 'expired_token' && !(hash['error_description'] =~ /The auth code expired/)
+        if hash[:error] == 'expired_token' && !(hash[:error_description] =~ /The auth code expired/)
           renew_access_token!
           retry_attempt += 1
           retry

data/lib/geoloqi/version.rb

@@ -1,5 +1,8 @@
 module Geoloqi
+  # Returns the current version of the Geoloqi ruby gem.
+  #
+  # @return [String]
   def self.version
-    '0.9.33'
+    '0.9.35'
   end
 end

data/spec/env.rb

@@ -20,4 +20,4 @@ end
 def api_url(path); "#{Geoloqi.api_url}/#{Geoloqi.api_version}/#{path}" end
 
 Wrong.config.alias_assert :expect
-include WebMock::API
+include WebMock::API

data/spec/geoloqi_config.rb

@@ -27,7 +27,7 @@ describe Geoloqi::Config do
   it 'displays log information if logger is provided and query is nil' do
     stub_request(:get, api_url('account/username')).
       with(:headers => {'Authorization'=>'OAuth access_token1234'}).
-      to_return(:body => {'username' => 'bulbasaurrulzok'}.to_json)
+      to_return(:body => {:username => 'bulbasaurrulzok'}.to_json)
     
     io = StringIO.new
     Geoloqi.config :client_id => CLIENT_ID, :client_secret => CLIENT_SECRET, :logger => io

data/spec/geoloqi_session_spec.rb

@@ -15,7 +15,7 @@ describe Geoloqi::Session do
     it 'should throw api error exception' do
       stub_request(:get, api_url('badmethodcall')).
               with(:headers => auth_headers).
-              to_return(:status => 404, :body => {'error' => 'not_found'}.to_json)
+              to_return(:status => 404, :body => {:error => 'not_found'}.to_json)
 
       expect { rescuing {Geoloqi::Session.new(:access_token => 'access_token1234').get('badmethodcall')}.class == Geoloqi::ApiError }
     end
@@ -23,13 +23,14 @@ describe Geoloqi::Session do
 
   describe 'custom exceptions scheme' do
     before do
-      @session = Geoloqi::Session.new :access_token => 'access_token1234', :config => {:use_dynamic_exceptions => true}
+      @session = Geoloqi::Session.new :access_token => 'access_token1234', :config => {:throw_exceptions => true,
+                                                                                       :use_dynamic_exceptions => true}
     end
 
     it 'should throw api error exception with custom name' do
       stub_request(:get, api_url('specialerror')).
               with(:headers => auth_headers).
-              to_return(:status => 404, :body => {'error' => 'not_found'}.to_json)
+              to_return(:status => 404, :body => {:error => 'not_found'}.to_json)
 
       expect { rescuing {@session.get('specialerror')}.class == Geoloqi::NotFoundError }
     end
@@ -37,7 +38,7 @@ describe Geoloqi::Session do
     it 'should throw api error exception without custom name if empty' do
       stub_request(:get, api_url('specialerror')).
               with(:headers => auth_headers).
-              to_return(:status => 404, :body => {'error' => ''}.to_json)
+              to_return(:status => 404, :body => {:error => ''}.to_json)
 
       expect { rescuing {@session.get('specialerror')}.class == Geoloqi::ApiError }
     end
@@ -51,10 +52,10 @@ describe Geoloqi::Session do
     it 'should not throw api error exception' do
       stub_request(:get, api_url('badmethodcall')).
               with(:headers => auth_headers).
-              to_return(:status => 404, :body => {'error' => 'not_found'}.to_json)
+              to_return(:status => 404, :body => {:error => 'not_found'}.to_json)
 
       response = @session.get 'badmethodcall'
-      expect {response['error'] == 'not_found'}
+      expect {response[:error] == 'not_found'}
     end
   end
 
@@ -66,7 +67,7 @@ describe Geoloqi::Session do
     it 'should respond to method calls in addition to hash' do
       stub_request(:get, api_url('account/username')).
         with(:headers => {'Authorization'=>'OAuth access_token1234'}).
-        to_return(:body => {'username' => 'bulbasaurrulzok'}.to_json)
+        to_return(:body => {:username => 'bulbasaurrulzok'}.to_json)
 
       response = @session.get 'account/username'
       expect { response['username'] == 'bulbasaurrulzok' }
@@ -95,18 +96,18 @@ describe Geoloqi::Session do
     it 'successfully makes call with array' do
       stub_request(:post, api_url('play_record_at_geoloqi_hq')).
         with(:headers => auth_headers, :body => [{:artist => 'Television'}].to_json).
-        to_return(:body => {'result' => 'ok'}.to_json)
+        to_return(:body => {:result => 'ok'}.to_json)
 
-      expect { @session.post('play_record_at_geoloqi_hq', [{:artist => 'Television'}])['result'] == 'ok' }
+      expect { @session.post('play_record_at_geoloqi_hq', [{:artist => 'Television'}])[:result] == 'ok' }
     end
 
     it 'successfully makes call to api' do
       stub_request(:get, api_url('layer/info/Gx')).
         with(:headers => auth_headers).
-        to_return(:status => 200, :body => {'layer_id' => 'Gx'}.to_json)
+        to_return(:status => 200, :body => {:layer_id => 'Gx'}.to_json)
 
       %w{/layer/info/Gx layer/info/Gx}.each do |path|
-        expect { @session.get(path)['layer_id'] == 'Gx' }
+        expect { @session.get(path)[:layer_id] == 'Gx' }
       end
     end
 
@@ -118,15 +119,15 @@ describe Geoloqi::Session do
       end
 
       it 'makes a location/history call with get and hash params' do
-        expect { @session.get('location/history', :count => 2)['points'].count == 2 }
+        expect { @session.get('location/history', :count => 2)[:points].count == 2 }
       end
 
       it 'makes a location/history call with get and query string directly in path' do
-        expect { @session.get('location/history?count=2')['points'].count == 2 }
+        expect { @session.get('location/history?count=2')[:points].count == 2 }
       end
 
       it 'makes a location/history call with get and query string params' do
-        expect { @session.get('location/history', 'count=2')['points'].count == 2 }
+        expect { @session.get('location/history', 'count=2')[:points].count == 2 }
       end
     end
   end
@@ -182,7 +183,7 @@ describe Geoloqi::Session do
     it 'fails with an exception' do
       stub_request(:post, api_url('message/send')).
               with(:headers => auth_headers('hey brah whats up let me in its cool 8)')).
-              to_return(:status => 401, :body => {'error' => 'invalid_token'}.to_json)
+              to_return(:status => 401, :body => {:error => 'invalid_token'}.to_json)
 
       begin
         @session.post 'message/send'
@@ -215,9 +216,9 @@ describe Geoloqi::Session do
       response = @session.get_auth '1234', 'http://example.com'
 
       {:access_token => 'access_token1234',
-                            :scope => nil,
-                            :expires_in => '86400',
-                            :refresh_token => 'refresh_token1234'}.each do |k,v|
+       :scope => nil,
+       :expires_in => '86400',
+       :refresh_token => 'refresh_token1234'}.each do |k,v|
         expect { response[k] == v }
       end
     end
@@ -246,7 +247,7 @@ describe Geoloqi::Session do
       response = @session.get 'account/username'
 
       expect { @session.auth[:access_token] == 'access_token1234' }
-      expect { response['username'] == 'bulbasaurrulzok' }
+      expect { response[:username] == 'bulbasaurrulzok' }
     end
     
     it 'does not attempt to refresh for auth code expire' do
@@ -292,7 +293,7 @@ describe Geoloqi::Session do
 
       stub_request(:get, api_url('account/username')).
         with(:headers => {'Authorization'=>'OAuth access_token4567'}).
-        to_return(:body => {'username' => 'pikachu4lyfe'}.to_json)
+        to_return(:body => {:username => 'pikachu4lyfe'}.to_json)
 
       @session.get 'account/username'
       expect { @session.auth[:access_token] == 'access_token4567' }

data/spec/geoloqi_spec.rb

@@ -33,7 +33,7 @@ describe Geoloqi do
       to_return(:body => {:result => 'ok'}.to_json)
 
     response = Geoloqi.get ACCESS_TOKEN, '/quick_get', {:lol => 'cats'}, 'Special' => 'header'
-    expect { response['result'] == 'ok' }
+    expect { response[:result] == 'ok' }
   end
 
   it 'makes post request' do
@@ -43,6 +43,6 @@ describe Geoloqi do
       to_return(:body => {:result => 'ok'}.to_json)
 
     response = Geoloqi.post ACCESS_TOKEN, '/quick_post', {:lol => 'dogs'}, 'Special' => 'header'
-    expect { response['result'] == 'ok' }
+    expect { response[:result] == 'ok' }
   end
 end

metadata

@@ -2,7 +2,7 @@
 name: geoloqi
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.9.33
+  version: 0.9.35
 platform: ruby
 authors: 
   - Kyle Drake
@@ -11,8 +11,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-10-25 00:00:00 -07:00
-default_executable: 
+date: 2012-01-08 00:00:00 Z
 dependencies: 
   - !ruby/object:Gem::Dependency 
     name: json
@@ -55,7 +54,7 @@ dependencies:
       requirements: 
         - - "="
           - !ruby/object:Gem::Version 
-            version: 0.5.0
+            version: 0.6.0
     type: :development
     version_requirements: *id004
   - !ruby/object:Gem::Dependency 
@@ -91,10 +90,21 @@ dependencies:
             version: 1.0.0
     type: :development
     version_requirements: *id007
+  - !ruby/object:Gem::Dependency 
+    name: yard
+    prerelease: false
+    requirement: &id008 !ruby/object:Gem::Requirement 
+      none: false
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            version: "0"
+    type: :development
+    version_requirements: *id008
 description: Powerful, flexible, lightweight interface to the awesome Geoloqi platform API! Uses Faraday, and can be used with Ruby 1.9 and EM-Synchrony for really fast, highly concurrent development.
 email: 
-  - kyledrake@gmail.com
-  - aaron@parecki.com
+  - kyle@geoloqi.com
+  - aaron@geoloqi.com
 executables: []
 
 extensions: []
@@ -104,26 +114,27 @@ extra_rdoc_files: []
 files: 
   - .gitignore
   - .travis.yml
+  - .yardopts
   - Gemfile
-  - README.markdown
+  - LICENSE.md
+  - README.md
   - Rakefile
   - examples/simple.rb
-  - examples/sinatra.rb
+  - examples/sinatra_simple.rb
   - examples/sinatra_synchrony.rb
   - geoloqi.gemspec
   - lib/geoloqi.rb
   - lib/geoloqi/config.rb
+  - lib/geoloqi/data/ca-certificates.crt
   - lib/geoloqi/error.rb
   - lib/geoloqi/response.rb
   - lib/geoloqi/session.rb
   - lib/geoloqi/version.rb
-  - license.txt
   - spec/env.rb
   - spec/geoloqi_api_error_spec.rb
   - spec/geoloqi_config.rb
   - spec/geoloqi_session_spec.rb
   - spec/geoloqi_spec.rb
-has_rdoc: true
 homepage: http://github.com/geoloqi/geoloqi-ruby
 licenses: []
 
@@ -147,9 +158,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: geoloqi
-rubygems_version: 1.5.1
+rubygems_version: 1.8.9
 signing_key: 
 specification_version: 3
 summary: Powerful, flexible, lightweight interface to the awesome Geoloqi platform API
 test_files: []
 
+has_rdoc: 

data/README.markdown

@@ -1,158 +0,0 @@
-Geoloqi Library for Ruby [![](https://secure.travis-ci.org/geoloqi/geoloqi-ruby.png)](http://travis-ci.org/geoloqi/geoloqi-ruby)
-===
-Powerful, flexible, lightweight interface to the awesome Geoloqi platform API! Uses Faraday, and can be used with Ruby 1.9 and EM-Synchrony for really fast, highly concurrent development.
-
-This library was developed with two goals in mind: to be as simple as possible, but also to be very powerful to allow for much higher-end development (multiple Geoloqi apps per instance, concurrency, performance).
-
-Installation
----
-
-    gem install geoloqi
-
-Basic Usage
----
-Geoloqi uses OAuth2 for authentication, but if you're only working with your own account, you don't need to go through the authorization steps! Simply go to your account settings on the [Geoloqi site](http://geoloqi.com), click on "Connections" and copy the OAuth 2 Access Token. You can use this token to run the following examples.
-
-If you just need to make simple requests, you can just make a simple get or post request from Geoloqi:
-
-    require 'geoloqi'
-    result = Geoloqi.get 'YOUR ACCESS TOKEN', 'layer/info/Gx'
-    puts response.inspect
-
-    # or a POST!
-    result = Geoloqi.post 'YOUR ACCESS TOKEN', 'layer/create', :name => 'Test Layer'
-
-If you're using Geoloqi with OAuth or making multiple requests, we recommend using the Geoloqi::Session class:
-
-	require 'geoloqi'
-	geoloqi = Geoloqi::Session.new :access_token => 'YOUR ACCESS TOKEN'
-	response = geoloqi.get 'layer/info/Gx'
-	puts response.inspect
-
-Which returns a hash with the following:
-
-	{"layer_id"=>"Gx", "user_id"=>"4", "type"=>"normal", "name"=>"USGS Earthquakes",
-	 "description"=>"Real-time notifications of earthquakes near you.",
-	 "icon"=>"http://beta.geoloqi.com/images/earthquake-layer.png", "public"=>"1",
-	 "url"=>"https://a.geoloqi.com/layer/description/Gx", "subscription"=>false, "settings"=>false}
-
-Both GET and POST are supported. To send a POST to create a place (in this case, the entire city of Portland, Oregon):
-
-	response = geoloqi.post 'place/create', {
-	  "layer_id" => "1Wn",
-	  "name" => "3772756364",
-	  "latitude" => "45.5037078163837",
-	  "longitude" => "-122.622699737549",
-	  "radius" => "3467.44",
-	  "extra" => {
-	    "description" => "Portland",
-	     "url" => "http://en.wikipedia.org/wiki/Portland"
-	  }
-	}
-
-This returns response['place_id'], which you can use to store and/or remove the place:
-
-	response = geoloqi.post "place/delete/#{response['place_id']}"
-
-Which returns response['result'] with a value of "ok".
-
-You can send query string parameters with get requests too:
-
-	geoloqi.get 'location/history', :count => 2
-	# or
-	geoloqi.get 'location/history?count=2'
-
-Hashie::Mash support
----
-Want to access in a more OOP/JSON style way? Use Hashie::Mash as the response object:
-
-    require 'geoloqi'
-    geoloqi = Geoloqi::Session.new :access_token => 'YOUR OAUTH2 ACCESS TOKEN GOES HERE', :config => {:use_hashie_mash => true}
-    response = geoloqi.get 'layer/info/Gx'
-    response.layer_id    # this works
-    response['layer_id'] # this works too
-    response[:layer_id]  # so does this
-
-Implementing OAuth2
----
-
-OAuth2 has been implemented so that it's very easy to store the session's authorization data in a hash. If the access token expires or becomes invalid, the refresh token is used to retrieve a fresh token. This is done automatically, so you don't have to worry about it. Just store the hash in a session, feed it back in on each request and you're good to go.
-
-Here is a simple Sinatra example implementing the OAuth2 flow with Geoloqi:
-
-	require 'rubygems'
-	require 'sinatra'
-	require 'geoloqi'
-
-	GEOLOQI_REDIRECT_URI = 'http://yourwebsite.net'
-
-	enable :sessions
-	set :session_secret, 'PUT A SECRET WORD HERE' # Encrypts the cookie session.. recommended.
-
-	def geoloqi
-	  @geoloqi ||= Geoloqi::Session.new :auth => session[:geoloqi_auth],
-	                                    :config => {:client_id => 'YOUR OAUTH CLIENT ID',
-	                                                :client_secret => 'YOUR CLIENT SECRET'}
-	end
-	
-	# If the access token expires, Geoloqi::Session will refresh inline!
-	# This after block makes sure the session gets the updated config.
-	after do
-	  session[:geoloqi_auth] = @geoloqi.auth
-	end
-  
-	get '/?' do
-	  geoloqi.get_auth(params[:code], GEOLOQI_REDIRECT_URI) if params[:code] && !geoloqi.access_token?
-	  redirect geoloqi.authorize_url(GEOLOQI_REDIRECT_URI) unless geoloqi.access_token?
-    
-	  username = geoloqi.get('account/username')['username']
-	  "You have successfully logged in as #{username}!"
-	end
-
-Now, here's a power example: Uses [sinatra-synchrony](http://github.com/kyledrake/sinatra-synchrony) to provide a massive concurrency improvement via EventMachine. This will allow your app to serve other requests, the app will not hang while waiting for content from the Geoloqi API. Works on anything that supports Thin (Rack, EY, Heroku, etc):
-
-	# To install deps: gem install sinatra sinatra-synchrony geoloqi
-	# To run from command line: ruby sinatra_synchrony.rb -s thin
-	require 'rubygems'
-	require 'sinatra'
-	require 'sinatra/synchrony'
-	require 'geoloqi'
-
-	GEOLOQI_REDIRECT_URI = 'http://example.com'
-
-	enable :sessions
-	set :session_secret, 'PUT A SECRET WORD HERE'
-
-	configure do
-	  Geoloqi.config :client_id => 'YOUR OAUTH CLIENT ID', :client_secret => 'YOUR CLIENT SECRET', :adapter => :em_synchrony
-	end
-
-	def geoloqi
-	  @geoloqi ||= Geoloqi::Session.new :auth => session[:geoloqi_auth]
-	end
-	
-	after do
-	  session[:geoloqi_auth] = @geoloqi.auth
-	end
-
-	get '/?' do
-	  session[:geoloqi_auth] = geoloqi.get_auth(params[:code], GEOLOQI_REDIRECT_URI) if params[:code] && !geoloqi.access_token?
-	  redirect geoloqi.authorize_url(GEOLOQI_REDIRECT_URI) unless geoloqi.access_token?
-	  username = geoloqi.get('account/username')['username']
-	  "You have successfully logged in as #{username}!"
-	end
-
-Found a bug?
----
-Let us know! Send a pull request or a patch. Questions? Ask! We're here to help. File issues, we'll respond to them!
-
-Authors
----
-* Kyle Drake
-* Aaron Parecki
-
-TODO / Possible projects
----
-* Plugin for Sinatra
-* Rails plugin (works fine as-is, but maybe we can make it easier?)
-* More Concrete API in addition to the simple one?