wschenk-workstreamer_api 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,9 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg
+rails_example/tmp
+rails_example/log/*
+rails_example/db/*.sqlite3
+

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Will Schenk
+
+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,23 @@
+= workstreamer_api
+
+This gem provides a ruby wrapper to interface with workstreamer.com.  It 
+depends on the "nokogiri" and "oauth" gems.  Also included is an example
+rails application which has an example of how to use the gem.
+
+Documentation on how to use the API can be found http://workstreamer.pbworks.com/
+
+To use the rails application, you need to first get a ClientApplication key from
+workstreamer as documented here: http://workstreamer.pbworks.com/Authentication
+
+Then edit rails_example/config/app_config.yml
+
+== Copyright
+
+Copyright (c) 2009 Workstreamer, LLC. See LICENSE for details.
+= workstreamer_api
+
+Description goes here.
+
+== Copyright
+
+Copyright (c) 2009 Will Schenk. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,52 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "workstreamer_api"
+    gem.summary = %Q{TODO}
+    gem.email = "wschenk@gmail.com"
+    gem.homepage = "http://github.com/wschenk/workstreamer_api"
+    gem.authors = ["Will Schenk"]
+    gem.rubyforge_project = "workstreamer_api"
+    gem.add_dependency 'oauth'
+    gem.add_dependency 'nokogiri'
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+  Jeweler::RubyforgeTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "workstreamer_api #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/workstreamer_api.rb

@@ -0,0 +1,375 @@
+require 'rubygems'
+require 'oauth'
+require 'pp'
+require 'json'
+require 'nokogiri'
+
+##
+# The WsApi module wraps all functionality needed to interface with the
+# workstreamer system.
+module WorkstreamerApi
+  ##
+  # Thrown if any call returns a 401; this means that you don't have a valid
+  # AccessToken.  It either never existed, or the token was invalidated by the
+  # user.
+  class Unauthorized < Exception ; end
+  class Forbidden < Exception ; end
+
+  ##
+  # This is the main workstreamer class.  The key and secret need to have
+  # been generated on the workstreamer site.  If the user doesn't have an
+  # AccessToken, this class can be used to generate a RequestToken.
+  class Api
+    ##
+    # Create a new workstreamer api instance.
+    #
+    #   key - the ClientApplication key generated for your application by
+    #         workstreamer.com at http://alpha.workstreamer.com/oauth_clients
+    #   secret - that matches the key
+    #   site - normally "alpha.workstreamer.com"  TODO This needs to be domain aware
+    #
+    # This is all that is needed to create a RequestToken for a user who
+    # hasn't given permission.  (See request_token for more info.)  If
+    # the user has already granted access, be sure to pass in
+    #
+    #   user_token - the AccessToken back from the oath provider
+    #   user_secret - the secret.
+    #
+    # See example/app/controllers/workstreamer_controller.callback for an example.
+    #
+    def initialize( key, secret, site = "http://localhost:3000", user_token = nil, user_secret = nil )
+      @key = key
+      @secret = secret
+      @site = site
+      @user_token = user_token
+      @user_secret = user_secret
+    end
+  
+    # Utility methods
+    
+    ##
+    # Returns a (cached) OAuth::Consumer
+    #
+    def consumer
+      @consumer ||= OAuth::Consumer.new @key, @secret, { :site => @site }
+    end
+  
+    ##
+    # This generates a request token for your application.  Once a RequestToken 
+    # is generated you then redirect the browser to the authorize_url.  e.g.
+    #
+    #   request_token = workstreamer.request_token
+    # 
+    #   session[:request_token] = request_token.token
+    #   session[:request_token_secret] = request_token.secret
+    # 
+    #   redirect_to request_token.authorize_url      
+    #
+    def request_token
+      @request_token ||= consumer.get_request_token
+    end
+
+    ##
+    # This returns a (cached) OAuth::AccessToken which can, in turn, be used
+    # to make remote HTTP calls to workstreamer.  All of the API wrapper calls use
+    # this method for the actual network transportation.
+    #
+    def access_token
+      @access_token ||= OAuth::AccessToken.new( consumer, @user_token, @user_secret )
+    end
+  
+    ##
+    # OAuth-orized HTTP GET to workstreamer.  Passed in a URL it will
+    # return a parsed object.  If JSON is requested, it will return a Hash.
+    # Otherwise, it will return a nogokiri XML object.  (convert_node_to_hash will
+    # transform a nogokiri XML object to a Hash but won't preserve the XML attributes.)
+    #
+    def get( url, json = true )
+      ret = access_token.get( url )
+      parse( ret, json )
+    end
+
+    ##
+    # OAuth-orized HTTP POST to workstreamer.  Passed in a URL and a hash or
+    # parameters it will return a parsed object.  If JSON is requested, it 
+    # will return a Hash. Otherwise, it will return a nogokiri XML object. 
+    # (convert_node_to_hash will transform a nogokiri XML object to a Hash 
+    # but won't preserve the XML attributes.)
+    #
+    def post( url, parameters, json = true )
+      ret = access_token.post url, parameters
+      parse( ret, json )
+    end
+  
+    ##
+    # Intepret a server response.  Raise WsApi::Unauthorized or WsApi::HTTPSuccess
+    # if there was an error, otherwise process the body through JSON.parse or
+    # Nokogiri::XML.
+    #
+    # TODO Should probably do this on the returned content-type rather than parameter
+    def parse( ret, json = true )
+      case ret
+      when Net::HTTPSuccess
+        # logger.debug ret.body
+        if json
+          return JSON.parse(ret.body)
+        else
+          return Nokogiri::XML( ret.body )
+        end
+      when Net::HTTPUnauthorized
+        raise Unauthorized
+      when Net::HTTPForbidden
+        raise Forbidden
+      else
+        puts ret
+        puts ret.body
+        raise Unknown
+      end
+    end
+
+    ##
+    # Used to build the parameter options; will only create an entry if
+    # the options is set, and will collapse arrays to comma seperated.
+    #
+    #   params - hash to set (destination)
+    #   key - the key to move over
+    #   options - hash that we're getting the data from (origin)
+    #
+    def set_options( params, key, options )
+      if options[key].is_a? Array
+        params[key] = options[key].join( "," )
+      elsif options[key]
+        params[key] = options[key]
+      end
+    end
+  
+    ##
+    # Simple method to turn a Nokogiri XML object into a ruby hash.
+    #
+    def convert_node_to_hash( xml )
+      ret = {}
+    
+      xml.children.each do |child|
+        if child.is_a? Nokogiri::XML::Element
+          subchildren = child.children
+          if subchildren.size == 1
+            ret[child.name] = child.inner_html
+          else
+            ret[child.name] = convert_node_to_hash( child )
+          end
+        end
+      end
+    
+      ret
+    end
+    
+    # Api methods
+    
+    ##
+    # Looks up information on a specific user.  If login is null, looks up the
+    # current/authorized user.
+    #
+    #   login - workstreamer login or user id
+    #
+    def user_info( login = nil )
+      url = "/user/info?format=json" 
+      url += "&login=#{login}" if login
+      get url
+    end
+  
+    ##
+    # Returns the user's current stream.
+    #
+    # TODO Stream filters
+    # TODO Unread counts
+    #
+    def stream
+      xml = get( "/post_apis/index?format=xml", false )
+    
+      ret = []
+    
+      (xml/'master-content').each do |mc|
+        ret << convert_node_to_hash( mc )
+      end
+    
+      ret
+    end
+  
+    ##
+    # Generate create_content method, which all other content creating methods
+    # -- except for FeedItems -- delegate to.  Depending upon the parameters, 
+    # content of a different type is created.
+    #
+    # See http://workstreamer.pbworks.com/Content-API for details on the
+    # parameters to pass in.
+    #
+    def create_content( parameters )
+      xml = post( "/post_apis/create", parameters, false )
+    
+      return false if xml.nil?
+    
+      node = xml.at( "result" )
+      return false if node.nil?
+      node.content == "SUCCESS"
+    end
+ 
+    ##
+    # Create a status update.  The content is parsed on the worksteamer server,
+    # so if you use @user or #tag the status update with be directed to a user
+    # and/or tagged.
+    #
+    #   message - The status update.
+    #
+    # TODO: Add project
+    #
+    def post_status_update( message )
+      create_content( {:content => message } )
+    end
+  
+    ##
+    # Create a direct message from the current user to user_name.
+    #
+    #   user_name - User to send the message to
+    #   message - The message
+    #
+    def post_direct_message( user_name, message )
+      create_content( {:content => "d @#{user_name} #{message}"} )
+    end
+  
+    ##
+    # Lookup multiple users at the same time.  Returns an array of the
+    # same type as user_info returns.
+    #
+    #   users - list of users
+    #
+    def lookup_users( users )
+      users = users.gsub( /([\s,]+)/, " " ).split( / / )
+
+      ret = {}
+      users.each do |login|
+        ret[login] = user_info( login )
+      end
+    
+      ret
+    end
+  
+    ##
+    # Lookup multuple users but return an array of user_ids
+    #
+    def lookup_user_ids( users )
+      lookup_users( users ).collect { |x| x[1]['id'] }
+    end
+  
+    ##
+    # Get project title and membership.
+    #
+    #  project - Project name or project id
+    #
+    def lookup_project( project )
+      get "/projects/view?format=json&name=#{URI::escape project}"
+    end
+  
+    ##
+    # Post a message with optional comma seperated tags.
+    #
+    #   title - the title of the message
+    #   body - the body of the message
+    #
+    # Options include:
+    #
+    #   :tags => "tag1,tag2,tag3"
+    #
+    #   :recipient_ids => "user_id1,user_id2,user_id3" or [user1_id, user2_id, user3_id]
+    #       or
+    #   :recipients => "tom,dick,harry" or ["tom", "dick", "harry"]
+    #
+    #   :project => "project_name"
+    #       or
+    #   :project_id => "project_id"
+    #
+    def post_message( title, body, options )
+      params = {:title => title, :content => body }
+      set_options( params, :tags, options )
+      options[:recipient_ids] = options[:recipient_ids].join( "," ) if options[:recipient_ids]
+      options[:recipient_ids] = lookup_user_ids( options[:recipients] ) if options[:recipients]
+      options[:recipients] = options[:recipient_ids]
+      set_options( params, :recipients, options )
+    
+      options[:project_id] = lookup_project( options[:project] )['id'] if options[:project]
+    
+      set_options( params, :project_id, options )
+    
+      pp params
+
+      create_content( params )
+    end
+  
+    ##
+    # Creates an event
+    #
+    #  title - Event title
+    #  start_date - Defaults to today
+    #  end_date - when the event ends
+    #
+    # TODO Add project and permissions.
+    def create_event( title, start_date = Date.today, end_date = nil )
+      params = {:title => title, :start_date => start_date }
+      params[:end_date] = end_date if end_date
+      create_content( params )
+    end
+  
+    ##
+    # Creates a task
+    #
+    #  title - the Task title
+    #  assigned_to - The user name or user id of who the task is assigned to
+    #  content - the body of the task
+    #  project_id - the optional project
+    #
+    def create_task( title, assigned_to, content, project_id = nil )
+      unless assigned_to =~ /^\d+$/
+        assigned_to = lookup_user_ids( assigned_to ).first
+      end
+    
+      create_content({:title => title, :assigned_to => assigned_to, :content => content, :project_id => project_id } )
+    end
+  
+    ##
+    # Create a comment on an existing content.
+    #
+    #   comment_text - the comment text
+    #   parent_id - the id of the MasterContent that you are commenting on.  This
+    #               is NOT the id of the content itself, but the enclosing
+    #               MasterContent
+    #
+    def create_comment( comment_text, parent_id )
+      create_content({:comment => comment_text, :reply_to => parent_id})
+    end
+  
+    ##
+    # Return everything we know about a content.
+    #
+    #   id - The content id.
+    #
+    def get_content( id )
+      url = "/post_apis/show?id=#{id}"
+    
+      xml = get url, false
+    
+      convert_node_to_hash xml
+    end
+  
+    ##
+    # Create a feed item.  Params are
+    #
+    #   :remote_id - The remote id for this feed item (uninterpreted)
+    #   :created_at - The created_at/published date, defaults to now
+    #   :title - Title of the item
+    #   :summary - The body of the item shown when expanded
+    #   :url - The url that represents the "original" item
+    #
+    def post_feed_item( params )
+      post "/feed/post_item", params, false
+    end
+  end
+end