duwanis-rubyku 0.0.3 → 0.1.0

data/README

@@ -8,33 +8,39 @@ Rubyku is a ruby library for accessing data via the Jaiku API.
 
 == FEATURES/PROBLEMS:
 
-Authorization against Jaiku is done using the Rubyku::Credentials object.
-  While the Jaiku API uses an API key instead of the username/password, I
-  thought it would be nice to allow for both.
-  So the api_key property on credentials will lazy-load itself (by logging
-  into the site and fetching it for you) if you populate the Credentials
-  object with a proper username and password.
-  Example:
-    cred = Rubyku::Credentials.new
-    cred.username = 'duwanis'
-    cred.password = 'notmyrealpassword'
-    cred.api_key
-    > "1n2o3t4m5y6a7p8i9k0e1y"
-    
-  Everything you may need to configure should be accessible via the
-  Rubyku::Settings object. So far:
-    proxy_url
-    proxy_port
-    jaiku_credentials #this is a place to save a default login, for a single-user app
-    logger            #an instance of Logger that will be used by rubyku for, well, logging.
-
-== SYNOPSIS:
-
-No synopsis yet, but I'm working on it
+Rubyku 0.1.0: Bringing home the [user]bacon
+
+Users are now fully functional (woo!). Messages still need some work
+done to them, and then after that we still need to work on being able
+to post. But you should be able to read anything you've ever wanted to
+read from a user now.
+
+== EXAMPLE:
+
+Just to whet your appetite:
+
+  #provide log in details for the service
+  cred = Rubyku::Credentials.new
+  cred.username = 'duwanis'
+  cred.password = 'password' # or cred.api_key = 'apikeygoeshere' if you want to do it that way
+  Rubyku::Settings.jaiku_credentials = cred #so you don't have to keep passing cred around
+  user = Rubyku::User.fetch 'duwanis' #and now we're off to the races
+  user.updates # => a list of Rubyku::Messages representing my latest updates
+  user.stream # => a list of Rubyku::Messages representing my contacts' latest updates
+
+etc. Have fun :)
 
 == REQUIREMENTS:
 
-none atm
+Currently, the only other gem required for rubyku is json > 1.0.0.
+I'm trying to keep it simple.
+
+== TESTING:
+
+Hah, notice how there isn't any automated testing?
+I'd really like to have automated test suites for rubyku, but it's
+not an easy thing to do since it's so tightly coupled with a web
+service that requires authentication. Let me know if you have any ideas, though.
 
 == INSTALL:
 

data/lib/rubyku/credentials.rb

@@ -1,4 +1,26 @@
 module Rubyku
+  ##
+  # This class represents the credentials necessary to log in
+  # to the Jaiku service in order to access non-public portions
+  # of the API.
+  # It has 3 fields:
+  # - +username+
+  # - +password+
+  # - +api_key+
+  # Only +username+ and +api_key+ are required to log in to Jaiku.
+  # Password is offered as a way to make things easier for the user:
+  # since API keys aren't easily memorable (and subject to change, in
+  # Jaiku's case), rubyku allows for setting the username and password
+  # alone. It will then fetch the api_key for the user.
+  # Example:
+  #   cred = Rubyku::Credentials.new
+  #   cred.username = 'duwanis'
+  #   cred.password = 'notmyrealpassword'
+  #   cred.api_key
+  #   => 'apikey1234567890'
+  #
+  # For a single-user app, one instance of Rubyku::Credentials should
+  # be created and saved on the Rubyku::Settings class.
   class Credentials
     attr_accessor :username
     attr_accessor :password
@@ -6,18 +28,12 @@ module Rubyku
     
     ##
     # returns the Jaiku API key for these credentials.
-    #  This is a lazy-load property. Since there is a method
-    #  that can be used to retrieve the API key with the username
-    #  and password, rubyku does not require you to specify that
-    #  key if you would rather specify a username and password.
+    # This is a lazy-load property. Since there is a method
+    # that can be used to retrieve the API key with the username
+    # and password, rubyku does not require you to specify that
+    # key if you would rather specify a username and password.
     #
-    # @return <String> the API key for this user.
-    #
-    # @raise <Rubyku::InvalidCredentialsError> indicates that the provided
-    #  username and password are not valid for Jaiku.
-    #
-    # @raise <RubykuError> indicates that there was an error communicating
-    #   to the Jaiku servers.
+    # returns: +String+ the API key for this user.
     #
     def api_key
       log = Rubyku::Settings.logger
@@ -43,24 +59,19 @@ module Rubyku
       
       ##
       # Given a username and password, retrieve that user's API key.
-      #   this works by logging the user in, stripping cookie information
-      #   off of the response, and then using that cookie information
-      #   to hit http://api.jaiku.com/key . All credit for this approach
-      #   to this python snippet on DZone: http://snippets.dzone.com/posts/show/5539
-      #   For the record, I'm torn about leaving this in. On the one hand it assumes
-      #   a lot about the internals of jaiku - on the other, it allows the user
-      #   to be oblivious to the API key and any changes it may undergo.
-      #
-      # @param username<String> the username to use for authentication.
-      #
-      # @param password<String> the password to use for authentication.
+      # this works by logging the user in, stripping cookie information
+      # off of the response, and then using that cookie information
+      # to hit http://api.jaiku.com/key . All credit for this approach
+      # to this python snippet on DZone: http://snippets.dzone.com/posts/show/5539
+      # For the record, I'm torn about leaving this in. On the one hand it assumes
+      # a lot about the internals of jaiku - on the other, it allows the user
+      # to be oblivious to the API key and any changes it may undergo.
       #
-      # @raise <Rubyku::InvalidCredentialsError> indicates that the provided
-      #  username and password are not valid for Jaiku.
+      # returns: +String+ the API key for the user, if found.
       #
-      # @raise <RubykuError> indicates that there was an error communicating
-      #   to the Jaiku servers.
-      #     
+      # raises:
+      # - Rubyku::InvalidCredentialsError - username/password were not valid.
+      # - Rubyku::Error - there was an error communicating with the Jaiku servers.    
       def fetch_api_key(username, password)
         log = Rubyku::Settings.logger
         
@@ -80,7 +91,7 @@ module Rubyku
           #If Jaiku returns anything other than a redirect (which is expected
           # for a successful logon), then something's broke.
           log.error "Jaiku returned something other than a 303. Something borked."
-          raise RubykuError, "Could not connect to http://www.jaiku.com/login to retrieve API key."
+          raise Rubyku::Error, "Could not connect to http://www.jaiku.com/login to retrieve API key."
         end
         
         #retrieve the cookie contents from the successful login result

data/lib/rubyku/errors.rb

@@ -3,9 +3,12 @@ module Rubyku
   class Error < RuntimeError
   end
   
+  # Rubyku exception thrown when a specified user is not found.
   class UserNotFoundError < Error
   end
   
+  # Rubyku exception thrown when provided credentials are not
+  # correct.
   class InvalidCredentialsError < Error
   end
 end

data/lib/rubyku/message.rb

@@ -0,0 +1,73 @@
+module Rubyku
+
+  ##
+  # This class represents messages within Jaiku. The exact
+  # representation of the data will be different, depending on
+  # whether or not this message was in response to another message.
+  # The properties for a Message object are:
+  # - +id+: The unique id Jaiku has assigned to this message.
+  # - +title+: The text of the message, or the title of the message if
+  #   this message is a response.
+  # - +entry_title+: The title of the original message (only present for comments)
+  # - +content+: The content of this message (only present for comments)
+  # - +pretty_content+: The content of this message + HTML formatting (only present for comments)
+  # - +url+: The url for this message.
+  # - +created_at+: An exact timestamp for this message's creation time.
+  # - +created_at_relative+: A friendly relative timestamp (e.g. '14 minutes ago')
+  # - +user+: An instance of +Rubyku::User+ representing the user who posted the message.
+  # - +comment+: A boolean property representing whether this message is a comment on another message.
+  class Message
+    attr_accessor :id
+    attr_accessor :title
+    attr_accessor :entry_title
+    attr_accessor :content
+    attr_accessor :pretty_content
+    attr_accessor :url
+    attr_accessor :created_at
+    attr_accessor :created_at_relative
+    attr_accessor :user
+    
+    def comment? #:nodoc:
+      return @comment
+    end
+    
+    def comment=(bool) #:nodoc:
+      @comment= bool
+    end
+    
+    class << self
+      ##
+      # Given a hash that represents the JSON data from Jaiku
+      # for a message, this method will build and return a
+      # Rubyku::Message with those properties.
+      #
+      def build_message_from_json(json)
+        m = Rubyku::Message.new
+        #the jaiku json objects look differently depending on
+        #whether or not they are in response to another message.
+        #if they are a response, the comment_id field will be
+        #present rather than the id field. A few other distinctions
+        #are captured below.
+        unless json['comment_id']
+          m.comment= false
+          m.id = json['id']
+        else
+          m.comment= true
+          m.id = json['comment_id']        
+          m.entry_title = json['entry_title']          
+          m.pretty_content = json['pretty_content']          
+        end
+
+        m.title = json['title']
+        m.content = json['content']
+        m.url = json['url']
+        m.created_at = DateTime.parse(json['created_at'])
+        m.created_at_relative = json['created_at_relative']
+        m.user = Rubyku::User.build_user_from_json(json['user'])
+        
+        m
+      end
+    end
+  end
+
+end

data/lib/rubyku/request.rb

@@ -1,17 +1,28 @@
 module Rubyku
 
+  ##
+  # This is a utility class that handles communication with the Jaiku server.
+  #
   class Request
     class << self
-    
+      ##
+      # This method uses the given url and credentials to retrieve
+      # JSON data from the Jaiku servers.
+      # returns: +Hash+ containing the JSON data.
+      #
       def retrieve_json_object(url_path, jaiku_credentials)
+        log = Rubyku::Settings.logger
+        log.info("About to request JSON from #{url_path}")
         url_path += jaiku_credentials.request_string
-
+        log.debug("Using full URL to fetch JSON: #{url_path}")
         url = URI.parse(url_path)
-        req = Net::HTTP::Get.new(url.path)
+        req = Net::HTTP::Get.new(url.request_uri)
         res = Net::HTTP::Proxy(Rubyku::Settings.proxy_url, Rubyku::Settings.proxy_port) \
                   .start(url.host, url.port) {|http|
                                                 http.request(req)
                                              }
+        log.info("Jaiku JSON response returned HTTP code #{res.code}")
+        log.debug("About to return JSON: " + res.body)
         JSON(res.body)
       end
     end

data/lib/rubyku/settings.rb

@@ -1,4 +1,19 @@
 module Rubyku
+  ##
+  # This class acts as a centralized location for configurable items
+  # in rubyku. The configurable properties are as follows:
+  # - +logger+: a ruby logger object where all messages are logged.
+  # - +jaiku_credentials+: an instance of Rubyku::Credentials that is used
+  #    throughout rubyku as the default credentials.
+  # - +proxy_url+: the url for an http proxy, if needed.
+  # - +proxy_port+: the port for an http proxy, if needed.
+  #
+  # The logger, by default, will log at Logger::INFO to logs/rubyku.log inside
+  # the project's source or gem folder. If you would like to integrate the rubyku
+  # logging statements into your own logs, simply replace the logger with your own
+  # at some point after including rubyku in your project.
+  # *WARNING*: a logger set to Logger::DEBUG will spit all kinds of user-sensitive
+  # information, and as such should only be used for testing. 
   class Settings
     class << self
       #Yay logger! Default logger is initialized below. Override it

data/lib/rubyku/user.rb

@@ -1,5 +1,13 @@
 module Rubyku
-
+  ##
+  # This class represents a user within the Jaiku system.
+  # It has the following attributes:
+  # - +avatar_url+: The url for locating the user's avatar picture.
+  # - +first_name+: The user's given first name.
+  # - +last_name+: The user's given last name.
+  # - +nick+: The user's unique username on Jaiku.
+  # - +jaiku_url+: The url where the user's jaiku account can be found.
+  # - +contacts+: A list of +Rubyku::User+ objects representing this user's contacts.
   class User
     attr_accessor :avatar_url
     attr_accessor :first_name
@@ -10,55 +18,69 @@ module Rubyku
 
     ##
     # Returns the list of contacts for the current user.
-    #  Contacts is the only property of User that is lazy-loaded.
-    #  This is because if it wasn't lazy-loaded, you'd be perpetually
-    #  creating user objects.
-    #
-    # @param jaiku_credentials<Rubyku::Credentials> the credentials to use
-    #   for authenticating with Jaiku. Defaults to any credentials set in <Rubyku::Settings>.
-    #
-    # @return <Array{Rubyku::User}> the users that this user follows on Jaiku. 
+    # Contacts is the only property of User that is lazy-loaded.
+    # This is because if it wasn't lazy-loaded, you'd be perpetually
+    # creating user objects.
     #
-    # @raise <Rubyku::UserNotFoundError> indicates that the user could not be found
-    #   in Jaiku.
-    #
-    # @raise <RubykuError> indicates that there was an error communicating
-    #   to the Jaiku servers.
+    # returns: +Array{Rubyku::User}+ the users that this user follows on Jaiku. 
     #
     def contacts(jaiku_credentials=Rubyku::Settings.jaiku_credentials)
       log = Rubyku::Settings.logger
       unless @contacts
-        log.info("contacts for user #{@username} requested - attempting to fetch.")
-        @contacts = User.fetchContacts(@username, jaiku_credentials)
+        log.info("contacts for user #{@nick} requested - attempting to fetch.")
+        @contacts = Rubyku::User.fetch(@nick, jaiku_credentials).contacts
       end
       
       @contacts
     end
 
+    ##
+    # Returns the user's most recent updates.
+    # This method will hit the server every time, so cache the results if you need to.
+    #
+    # returns: +Array{Rubyku::Message}+ this user's most recent updates
+    #
+    def updates(jaiku_credentials=Rubyku::Settings.jaiku_credentials)
+      log = Rubyku::Settings.logger
+      log.info("Requesting updates from user #{@nick}")
+      url = "http://%s.jaiku.com/feed/json" % @nick
+      updates_json = Rubyku::Request.retrieve_json_object(url, jaiku_credentials)
+      updates_json['stream'].map { |m| Rubyku::Message.build_message_from_json(m) }
+    end
+
+    ##
+    # Returns the stream for this user (updates from their contacts, as they see
+    # on the home page).
+    # This method will hit the server everytime, so cache the results if you need to.
+    #
+    # returns: +Array{Rubyku::Message}+ the messages in this user's stream.
+    #
+    def stream(jaiku_credentials=Rubyku::Settings.jaiku_credentials)
+      log = Rubyku::Settings.logger
+      log.info("Requesting stream for user #{@nick}")
+      url = "http://%s.jaiku.com/contacts/feed/json" % @nick
+      stream_json = Rubyku::Request.retrieve_json_object(url, jaiku_credentials)
+      stream_json['stream'].map { |m| Rubyku::Message.build_message_from_json(m) }
+    end
+
     class << self
       ##
       # Retrieves a user's information from Jaiku.
-      #  All properties but contacts are loaded. @see <Rubyku::User.contacts>
-      #
-      # @param username<String> the user to fetch.
-      # 
-      # @param jaiku_credentials<Rubyku::Credentials> the credentials to use
-      #   for authenticating with Jaiku. Defaults to any credentials set in <Rubyku::Defaults>.
-      #
-      # @return <Rubyku::User> the requested user.
       #
-      # @raise <Rubyku::UserNotFoundError> indicates that the user could not be found
-      #   in Jaiku.
+      # returns: Rubyku::User the requested user.
       #
-      # @raise <RubykuError> indicates that there was an error communicating
-      #   to the Jaiku servers.      
-      # 
       def fetch(username,jaiku_credentials=Rubyku::Settings.jaiku_credentials)  
         req_url = "http://%s.jaiku.com/json" % username
         json = Rubyku::Request.retrieve_json_object(req_url, jaiku_credentials)
         build_user_from_json(json)
       end
       
+      ##
+      # Given a hash representing the JSON data for a user from Jaiku,
+      # this method maps those JSON properties to a +Rubyku::User+ object
+      # and returns it.
+      # Contacts are loaded if present.
+      #
       def build_user_from_json(json)
         user = Rubyku::User.new
         user.nick= json['nick']

data/lib/rubyku/version.rb

@@ -1,8 +1,8 @@
 module Rubyku #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
-    MINOR = 0
-    TINY  = 3
+    MINOR = 1
+    TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/lib/rubyku.rb

@@ -1,3 +1,5 @@
+#:include:../README
+
 # Just to make our requires at the top of the gem a little easier.
 require 'pathname'
 $:.unshift(Pathname(__FILE__).dirname.expand_path)
@@ -6,9 +8,12 @@ require 'net/http'
 require 'logger'
 require 'rubygems'
 require 'json'
+require 'date'
+
 #rubyku requires
 require 'rubyku/settings'
 require 'rubyku/errors'
+require 'rubyku/message'
 require 'rubyku/user'
 require 'rubyku/credentials'
 require 'rubyku/version'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: duwanis-rubyku
 version: !ruby/object:Gem::Version 
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors: 
 - Tommy Morgan
@@ -27,28 +27,29 @@ executables: []
 
 extensions: []
 
-extra_rdoc_files: 
-- LICENSE
-- README
+extra_rdoc_files: []
+
 files: 
-- LICENSE
-- README
-- Rakefile
 - lib/rubyku.rb
-- lib/rubyku/version.rb
 - lib/rubyku/credentials.rb
-- lib/rubyku/settings.rb
-- lib/rubyku/user.rb
 - lib/rubyku/errors.rb
+- lib/rubyku/message.rb
 - lib/rubyku/request.rb
-- test/test_helper.rb
-- test/test_rubyku.rb
+- lib/rubyku/settings.rb
+- lib/rubyku/user.rb
+- lib/rubyku/version.rb
+- LICENSE
+- README
+- logs/
 has_rdoc: true
 homepage: http://github.com/duwanis/rubyku
 post_install_message: 
 rdoc_options: 
+- --title
+- Rubyku - Jaiku for Ruby
 - --main
-- README
+- lib/rubyku.rb
+- --line-numbers
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -70,6 +71,5 @@ rubygems_version: 1.0.1
 signing_key: 
 specification_version: 2
 summary: A Ruby API for accessing Jaiku.
-test_files: 
-- test/test_helper.rb
-- test/test_rubyku.rb
+test_files: []
+

data/Rakefile

@@ -1,7 +0,0 @@
-task :build_gem do
-  system("gem build rubyku.gemspec")
-end
-
-task :prepare_commit do
-  system("rm logs/*")
-end

data/test/test_helper.rb

@@ -1,2 +0,0 @@
-require 'test/unit'
-require File.dirname(__FILE__) + '/../lib/rubyku'

data/test/test_rubyku.rb

@@ -1,11 +0,0 @@
-require File.dirname(__FILE__) + '/test_helper.rb'
-
-class TestRubyku < Test::Unit::TestCase
-
-  def setup
-  end
-  
-  def test_truth
-    assert true
-  end
-end