dopplr 0.1.0

data/README.md

@@ -0,0 +1,60 @@
+# Dopplr
+
+This library provides objects for talking to some of the data available in Dopplr, The Social Atlas. It is essentially a multi-user wrapping of the Dopplr API, with each object being bound to a client.
+
+## Usage
+
+### First things first
+
+Require the Dopplr library and create a `Dopplr::Client` instance. Return a login URL for the user to obtain a token, store the token for that user.
+
+    require 'dopplr'
+    
+    client = Dopplr::Client.new             #=> #<Dopplr::Client:0x578208 ...>
+    client.login_url "http://www.you.com/"  #=> "https://www.dopplr.com/api/..."
+
+Now that you have a single-use token, assign it to the `Dopplr::Client` object and generate a session token.
+
+    client.token = '1a2b3c4d5e6f'     #=> '1a2b3c4d5e6f'
+    client.create_session             #=> '3c4d5e6f1a2b'
+
+### Instantiating and working with objects
+
+All Dopplr objects are created using the client as a base, you can then branch of from them to dig deeper.
+
+    mike      = client.traveller      #=> Dopplr::Traveller for the token holder
+    chicago   = client.city 4887398   #=> Dopplr::City for ID 4887398
+    montreal  = mike.home_city        #=> Dopplr::City for mike's home city
+    trip      = mike.trips.first      #=> Dopplr::Trip for mike's first trip
+
+Return some basic information about each object.
+
+    montreal.country      #=> "Canada"
+    montreal.timezone     #=> "America/Montreal"
+    montreal.localtime    #=> Wed Jul 22 09:30:15 2009
+    
+    chicago.url           #=> "http://www.dopplr.com/place/us/il/chicago"
+    chicago.latitude      #=> 41.85
+    chicago.longitude     #=> -87.6501
+    
+    mike.name             #=> "Mike Richards"
+    mike.status           #=> "is at home in Montreal"
+    mike.travel_today     #=> false
+    
+    trip.city.name        #=> "Calgary"
+    trip.start            #=> Sat Feb 16 00:00:00 2008
+    trip.return_transport #=> "plane"
+
+Get trips and fellows for a particular traveller.
+
+    mike.trips            #=> [#<Dopplr::Trip:0x56f4a0 ...>, ...]
+    
+    mike.fellows          #=> {:can_see_trips_of => [#<Dopplr::Traveller:0x570954 ...>, ...],
+                               :shows_trips_to => [#<Dopplr::Traveller:0x59e8b1 ...> ...]}
+
+Return a new `Dopplr::City` object without knowing the geoname_id (I'm feeling lucky).
+
+    portland = client.find_city "Portland"
+    
+    portland.country      #=> "United States"
+    portland.geoname_id   #=> 5746545

data/lib/dopplr/city.rb

@@ -0,0 +1,27 @@
+module Dopplr
+  class City
+    attr_reader :name, :country, :timezone, :localtime, :latitude, :longitude
+    attr_reader :geoname_id, :country_code, :woeid, :rgb, :utc_offset, :url
+    
+    def initialize(client, id)
+      @client = client
+      @geoname_id = id
+      populate
+    end
+    
+    def populate
+      info = @client.get('city_info', :geoname_id => @geoname_id)['city']
+      @name         = info['name']
+      @country      = info['country']
+      @timezone     = info['timezone']
+      @latitude     = info['latitude']
+      @longitude    = info['longitude']
+      @country_code = info['country_code']
+      @woeid        = info['woeid']
+      @rgb          = info['rgb']
+      @utc_offset   = info['utcoffset']
+      @url          = info['url']
+      @localtime    = Time.parse info['localtime'].slice(0..-7)
+    end
+  end
+end

data/lib/dopplr/client.rb

@@ -0,0 +1,68 @@
+module Dopplr
+  class Client
+    attr_accessor :token
+    
+    def initialize(token=nil)
+      @token = token
+    end
+    
+    # Makes an API call with @token.
+    def get(path, params={})
+      params['format'] = 'js'
+      params_uri = URI.escape(params.collect{|key,value| "#{key}=#{value}"}.join('&'))
+      url = "/api/#{path}/?#{params_uri}"
+      http = Net::HTTP.new("www.dopplr.com", 443)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      http.start do |http|
+        request = Net::HTTP::Get.new url, 'Authorization' => "AuthSub token=\"#{@token}\""
+        JSON.parse(http.request(request).body)
+      end
+    end
+    
+    # Returns a URL for getting a token.
+    def login_url(url)
+      return "https://www.dopplr.com/api/AuthSubRequest?scope=#{CGI.escape("http://www.dopplr.com/")}&next=#{CGI.escape(url)}&session=1"
+    end
+    
+    # Changes @token into a session token.
+    def create_session
+      @token = get('AuthSubSessionToken')['token']
+    end
+    
+    # Performs a search query.
+    def search(term, type=:all)
+      if type == :all
+        get 'search', :q => term
+      elsif type == :city
+        get 'city_search', :q => term
+      elsif type == :traveller
+        get 'traveller_search', :q => term
+      end
+    end
+    
+    # Returns a new City object.
+    def city(city_id)
+      City.new(self, city_id)
+    end
+    
+    # I'm feeling lucky city search.
+    def find_city(name)
+      city get('city_search', :q => name)['city'][0]['geoname_id']
+    end
+    
+    # Returns a new Trip object.
+    def trip(trip_id)
+      Trip.new(self, trip_id)
+    end
+    
+    # Returns a new Traveller object.
+    def traveller(username = nil)
+      if username
+        Traveller.new(self, username)
+      else
+        Traveller.new(self)
+      end
+    end
+  end
+end

data/lib/dopplr/traveller.rb

@@ -0,0 +1,72 @@
+module Dopplr
+  class Traveller
+    attr_reader :nick, :name, :status, :travel_today, :icon_id, :email_sha1, :url
+    
+    def initialize(client, user = nil)
+      @client = client
+      @params = {}
+      @params[:traveller] = user if user
+      populate
+    end
+    
+    def populate
+      info = @client.get('traveller_info', @params)['traveller']
+      @nick         = info['nick']
+      @name         = info['name']
+      @status       = info['status']
+      @travel_today = info['travel_today']
+      @icon_id      = info['icon_id']
+      @email_sha1   = info['sha1email']
+      @url          = info['url']
+    end
+    
+    def current_city(options = {})
+      unless @current_city && !options[:force]
+        info = @client.get('traveller_info', @params)['traveller']
+        @current_city = City.new @client, info['current_city']['geoname_id']
+      end
+      @current_city
+    end
+    
+    def home_city(options = {})
+      unless @home_city && !options[:force]
+        info = @client.get('traveller_info', @params)['traveller']
+        @home_city = City.new @client, info['home_city']['geoname_id']
+      end
+      @home_city
+    end
+    
+    def trips(options = {})
+      unless @trips && !options[:force]
+        trips = @client.get('trips_info', @params)['trip']
+        if !trips.empty?
+          @trips = trips.map do |trip|
+            Trip.new @client, trip['id']
+          end
+        end
+      end
+      @trips ||= []
+    end
+    
+    def fellows(options = {})
+      unless @fellows && !options[:force]
+        fellows = @client.get('fellows', @params)
+        fellows['can_see_trips_of'].map! do |fellow|
+          Traveller.new @client, fellow['nick']
+        end
+        fellows['shows_trips_to'].map! do |fellow|
+          hash = fellow.inject({}) do |memo, (key, value)|
+            memo[key.to_sym] = value
+            memo
+          end
+          Struct.new(*hash.keys).new(*hash.values_at(*hash.keys))
+        end
+        @fellows = fellows.inject({}) do |memo, (key, value)|
+          memo[key.to_sym] = value
+          memo
+        end
+      end
+      @fellows
+    end
+  end
+end

data/lib/dopplr/trip.rb

@@ -0,0 +1,31 @@
+module Dopplr
+  class Trip
+    attr_reader :start, :finish, :city, :outgoing_transport, :return_transport, :tags, :notes
+    attr_reader :trip_id, :url
+    
+    def initialize(client, id)
+      @client = client
+      @trip_id = id
+      populate
+    end
+    
+    def populate
+      info = @client.get('trip_info', :trip_id => @trip_id)['trip']
+      @outgoing_transport = info['outgoing_transport_type']
+      @return_transport   = info['return_transport_type']
+      @tags               = info['tag']
+      @notes              = info['note']
+      @url                = info['url']
+      @start              = Time.parse info['start']
+      @finish             = Time.parse info['finish']
+    end
+    
+    def city(options = {})
+      unless @city && !options[:force]
+        info = @client.get('trip_info', :trip_id => @trip_id)['trip']
+        @city = City.new @client, info['city']['geoname_id']
+      end
+      @city
+    end
+  end
+end

data/lib/dopplr.rb

@@ -0,0 +1,12 @@
+$: << File.dirname(__FILE__)
+
+require 'rubygems'
+require 'time'
+require 'cgi'
+require 'net/https'
+require 'json'
+
+require 'dopplr/client'
+require 'dopplr/traveller'
+require 'dopplr/city'
+require 'dopplr/trip'

data/test/helpers.rb

@@ -0,0 +1,7 @@
+$: << File.dirname(__FILE__) + '/..'
+
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+require 'lib/dopplr'

data/test/unit/client_test.rb

@@ -0,0 +1,41 @@
+require File.dirname(__FILE__) + '/../helpers'
+
+class ClientTest < Test::Unit::TestCase
+  context "A client" do
+    setup do
+      @client = Dopplr::Client.new
+    end
+    
+    should "provide a proper login url" do
+      assert_equal @client.login_url("http://www.you.com/"), "https://www.dopplr.com/api/AuthSubRequest?scope=http%3A%2F%2Fwww.dopplr.com%2F&next=http%3A%2F%2Fwww.you.com%2F&session=1"
+    end
+    
+    context "with a valid session token" do
+      setup do
+        @client.token = 'TOKEN'
+      end
+      
+      should "have a base traveller" do
+        traveller = @client.traveller
+        assert_equal traveller.nick, 'mikeric'
+      end
+      
+      should "be able to create new objects" do
+        assert @client.city 6173331
+        assert @client.trip 525522
+      end
+      
+      should "be able to perform search queries" do
+        city_search = @client.search "Montreal", :city
+        assert city_search['city']
+        traveller_search = @client.search "Mike", :traveller
+        assert traveller_search['traveller']
+      end
+      
+      should "be able to find a city" do
+        city = @client.find_city "Portland"
+        assert_equal city.geoname_id, 5746545
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification 
+name: dopplr
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Mike Richards
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-06 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.5
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: 
+email: mike22e@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- README.md
+- lib/dopplr.rb
+- lib/dopplr/client.rb
+- lib/dopplr/city.rb
+- lib/dopplr/traveller.rb
+- lib/dopplr/trip.rb
+- test/helpers.rb
+- test/unit/client_test.rb
+has_rdoc: true
+homepage: http://github.com/mikeric/dopplr
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: A Ruby library for talking to the Dopplr API
+test_files: []
+