minmb-teambox-client 0.4.0

data/lib/teambox-client/models/upload.rb

@@ -0,0 +1,27 @@
+module Teambox
+  class Upload < Teambox::Resource
+    def user
+      get_or_make_reference('User', @data, 'user_id')
+    end
+    
+    def project
+      get_or_make_reference('Project', @data, 'project_id')
+    end
+    
+    def page
+      get_or_make_reference('Project', @data, 'project_id')
+    end
+    
+    def page_slot
+      get_or_make_reference('PageSlot', @data, 'page_slot_id')
+    end
+    
+    def comment
+      get_or_make_reference('Comment', @data, 'comment_id')
+    end
+    
+    def url #:nodoc:
+      "/projects/#{@data['project_id']}/#{@data['id']}"
+    end
+  end
+end

data/lib/teambox-client/models/user.rb

@@ -0,0 +1,11 @@
+module Teambox
+  class User < Teambox::Resource
+    def name
+      "#{@data['first_name']} #{@data['last_name']}"
+    end
+    
+    def url #:nodoc:
+      "/users/#{@data['id']}"
+    end
+  end
+end

data/lib/teambox-client/reference_list.rb

@@ -0,0 +1,49 @@
+# Methods for handling references list
+module ReferenceList
+  # Generate references hash from JSON data
+  def generate_references(data)
+    @references = {}
+    @references.tap { |h| data.each {|ref| h[ref['type'] + ref['id'].to_s] = Teambox.create_model(ref['type'], ref, self) } }
+  end
+  
+  # References resource in the current Teambox::ResultSet
+  def set_reference(klass, resource)
+    real_resource = if resource.is_a? Teambox::Resource
+      resource
+    else
+      Teambox.const_get(klass).new(resource, self)
+    end
+    
+    @references[klass.to_s + real_resource.id.to_s] = real_resource
+    real_resource
+  end
+  
+  # Gets a referenced object. e.g:
+  #   get_reference('User', 1)
+  def get_reference(klass, id)
+    @references[klass.to_s + (id||'').to_s]
+  end
+  
+  # get reference based on data. Makes new resource if reference does not exist. e.g.
+  #   get_or_make_reference('User', @data, 'user_id')
+  def get_or_make_reference(klass, data, field_id)
+    get_reference(klass, data[field_id]) || set_reference(klass, {}.merge({'id' => data[field_id]}))
+  end
+  
+  # get a list of references based on data. Makes a new resource for each references which doesnot exist.
+  def get_or_make_references(klass, data, field_id, field_data=nil)
+    if data[field_data]
+      data[field_data].map do |object|
+        get_reference(klass, object['id']) ||
+        set_reference(klass, object)
+      end
+    elsif data[field_id]
+      data[field_id].map do |object_id|
+        get_reference(klass, object_id) ||
+        set_reference(klass, {'id' => object_id})
+      end
+    else
+      []
+    end
+  end
+end

data/lib/teambox-client/result_set.rb

@@ -0,0 +1,72 @@
+module Teambox
+  # This represents a list of objects along with referenced objects returned by the API.
+  #
+  # == Basic Usage
+  #
+  # A Teambox::ResultSet is usually returned from a get request from Teambox::Client. e.g.:
+  #
+  #   list = client.get('/projects') # Teambox::ResultSet
+  #   puts "Returned #{list.length} projects"
+  #
+  # The Teambox API only returns a limited amount of objects per request (currently 50), 
+  # so the methods prev, next, and empty? are provided to navigate the list of objects. 
+  # e.g. To get all projects, you can use something like:
+  #
+  #   project_list = []
+  #   list = client.get('/projects')
+  #   while !list.empty?
+  #     items += list.objects
+  #     list = list.prev
+  #   end
+  #
+  class ResultSet
+    include ReferenceList
+    attr_reader :first_id, :last_id, :client, :references, :objects
+    
+    def initialize(client, request, objects, references) #:nodoc:
+      @client = client
+      @request = request
+      generate_references(references)
+      @objects = objects.map { |o| Teambox.create_model(o['type'], o, self) }
+      
+      id_list = objects.map{|obj| obj['id']}.sort
+      @first_id = id_list[0]
+      @last_id = id_list[-1]
+    end
+    
+    # Yields for each object
+    def each(&block)
+      @objects.each(&block)
+    end
+    
+    # Yields for each object
+    def map(&block)
+      @objects.map(&block)
+    end
+    
+    # Length of object list
+    def length
+      @objects.length
+    end
+    
+    # Is the object list empty?
+    def empty?
+      @objects.length == 0
+    end
+    
+    # Gets older items as a Teambox::ResultSet
+    def prev
+      @client.get(@request[:url], {}, :query => (@request[:query]).merge(:max_id => @first_id))
+    end
+    
+    # Gets newer items as a Teambox::ResultSet
+    def next
+      @client.get(@request[:url], {}, :query => (@request[:query]).merge(:since_id => @last_id))
+    end
+    
+    # Indexes into object array
+    def [](idx)
+      @objects[idx]
+    end
+  end
+end

data/lib/teambox-client/teambox.rb

@@ -0,0 +1,288 @@
+# Teambox API wrapper. See Teambox::Client for more details.
+module Teambox
+  # This is the entrypoint to the Teambox API.
+  #
+  # == Basic Usage
+  # 
+  # Create a Teambox::Client, passing in your authentication detials in :auth.
+  # Then use one of the helper methods to get data.
+  #
+  #   client = Teambox::Client.new(:auth => {:user => 'frank', :password => 'papapa'})
+  #   client.current_user # == frank
+  #   client.project('earthworks')
+  #
+  # The methods get, post, put, delete, and safe_get are provided in case you want to 
+  # access an API method not covered by a helper. e.g.:
+  #
+  #   client.get('/account')
+  #
+  # The API will either return a Teambox::Resource, or a Teambox::ResultSet in the case of
+  # index methods.
+  #
+  # Errors returned by the api are thrown as a Teambox::APIError, so beware of this when writing
+  # your api code.
+  #
+  #   begin
+  #     client.project('earthworks').create_conversation(:name => 'Serious discussion', :body => 'We need a serious discussion')
+  #   rescue Teambox::APIError => e
+  #     puts "Something went wrong: #{e.inspect}"
+  #   end
+  #
+  # == OAuth authentication
+  #
+  # To authenticate via OAuth (currently not supported on teambox.com), you will need
+  # to pass in your consumer key, secret, and redirect url in :auth. Then use authorize_url 
+  # and authorize to complete authentication.
+  #
+  #   client = Teambox::Client.new(:auth => {
+  #     :oauth_app_id => 'h6K1Ru9sVFbPGEK5v9gQFPHTNZ5IRsVCGNeGENQ3',
+  #     :oauth_app_secret => 'fec4x9P7atC666JzF6WEZIeY6pVv1lCp6aLfVJBw',
+  #     :redirect_uri => 'http://www.myapp.com/auth/teambox'})
+  #   client.authorize_url # Open this in your browser
+  #   client.authenticate(:oauth_verifier => '1234') # Code returned from teambox
+  #
+  #
+  class Client
+    include HTTParty
+    include Teambox::OAuth
+    
+    # Initializes the Teambox client
+    def initialize(opts = {})
+      opts[:base_uri] ||= 'https://teambox.com/api/1'
+      self.class.base_uri(opts[:base_uri])
+      
+      @base_uri = opts[:base_uri]
+      @auth = opts[:auth] || {}
+      @consumer = consumer if oauth?
+      
+      authenticate(opts[:auth])
+    end
+    
+    # Returns true if oauth is being used for authentication
+    def oauth?
+      !@auth[:oauth_app_id].nil?
+    end
+    
+    # Returns the URL required to authenticate access if using OAuth
+    def authorize_url(opts={})
+      if oauth?
+        @consumer.web_server.authorize_url({:redirect_uri => @auth[:redirect_uri]}.merge(opts))
+      else
+        nil
+      end
+    end
+    
+    # Authenticates the client with teambox
+    def authenticate(opts={})
+      @current_user = nil
+      if oauth?
+        if opts[:oauth_verifier]
+          authorize_from_request(opts[:oauth_verifier])
+        elsif opts[:oauth_token]
+          @auth.merge!({:oauth_token => opts[:oauth_token]})
+          authorize_from_access
+        end
+      else
+        if opts[:user]
+          @auth.merge!({:user => opts[:user], :password => opts[:password]})
+          self.class.basic_auth(@auth[:user], @auth[:password])
+        end
+      end
+      
+      !current_user.nil?
+    end
+
+    # Is the client is authenticated?
+    def authenticated?
+      !current_user.nil?
+    end
+
+    # Current user the client is logged in as
+    def current_user
+      @current_user ||= safe_get('/account')
+    end
+
+    # Performs a GET on path
+    def get(path, query={}, options={})
+      api_unwrap perform_request(:get, path, {:query => query}.merge(options)), {:url => path, :query => query}
+    end
+
+    # Performs a POST on path
+    def post(path, query={}, options={})
+      api_unwrap perform_request(:post, path, {:body => query}.merge(options)), {:url => path, :body => query}
+    end
+
+    # Performs a PUT on path
+    def put(path, query={}, options={})
+      api_unwrap perform_request(:put, path, {:body => query}.merge(options)), {:url => path, :body => query}
+    end
+
+    # Performs a DELETE on path
+    def delete(path, query={}, options={})
+      api_unwrap perform_request(:delete, path, {:body => query}.merge(options)), {:url => path, :body => query}
+    end
+    
+    # Performs a GET on path, catching any exceptions
+    def safe_get(path, query={}, options={})
+      api_unwrap(perform_request(:get, path, {:query => query}.merge(options)), {:url => path, :query => query}) rescue nil
+    end
+    
+    # urls
+    
+    # Gets a list Teambox::Project corresponding to the current users project list
+    def projects(query={})
+      get('/projects', query)
+    end
+    
+    # Gets a Teambox::Project by id or permalink
+    def project(id)
+      get("/projects/#{id}")
+    end
+
+    protected
+    
+    # Internal request handler
+    def perform_request(method, path, options)
+      options[:headers] ||= {}
+      headers = options[:headers]
+      
+      options[:query] ||= {}
+      options[:query][:access_token] = @access_token.token if @access_token
+      self.class.send(method, path, options)
+    end
+    
+    # Decodes response and returns appropriate API object
+    def api_unwrap(response, request={})
+      data = JSON.parse(response.body) rescue nil
+      if [200, 201, 202].include? response.response.code.to_i
+        raise StandardError.new('Please update your Teambox') unless response.has_key?('type')
+        if data['type'] == 'List'
+          ResultSet.new(self, request, data['objects'], data['references'])
+        else
+          Teambox.create_model(data['type'], data, ResultSet.new(self, request, [], []))
+        end
+      else
+        error_list = data ? data['errors'] : {'type' => 'UnknownError', 'message' => data}
+        error_list['type'] = error_list['type'][0] if error_list['type'].is_a? Array
+        error_list['message'] = error_list['message'][0] if error_list['message'].is_a? Array
+        raise APIError.new(response.response.code, error_list)
+      end
+    end
+
+  end
+
+  # Exception handling for API Errors
+  class APIError < StandardError
+    attr_reader :error_type  # Type of error. See the API Docs for a list of error types
+    attr_reader :status_code # HTTP status code returned
+    def initialize(status_code, details)
+      @error_type = details['type'].to_sym
+      @status_code = status_code
+      super(details['message'] || details['type'])
+    end
+  end
+  
+  # Exception handling unknown Teambox::Resource types
+  class UnknownResourceError < APIError
+    def initialize(type)
+      super(200, {'type' => 'UnknownResource', :message => "Unknown Resource #{type}"})
+    end
+  end
+
+  def self.create_model(type, data, list=nil) #:nodoc:
+    klass = const_get(type.to_sym) rescue nil
+    if klass
+      klass.new data, list
+    else
+      throw UnknownResourceError.new(type)
+    end
+  end
+  
+  # Represents an object located on Teambox.
+  #
+  # Most resources belonging to a Teambox::Project can be modified, in which case you can use
+  # the save, destroy, and reload methods.
+  #
+  # All attributes are exposed by the method_missing handler.
+  class Resource
+    include ReferenceList
+  
+    attr_accessor :list, :data
+    attr_reader :references
+    
+    def initialize(data, result_list=nil)
+      @data = data
+      @list = result_list || ResultSet.new(nil, nil, [], [])
+      if @data['references']
+        generate_references(@data['references'])
+      else
+        @references = result_list ? result_list.references : {}
+      end
+    end
+
+    def id
+      @data['id']
+    end
+    
+    # The time this object was created
+    def created_at
+      @data.has_key?('created_at') ? Time.parse(data['created_at']) : nil
+    end
+    
+    # The last time this object was updated
+    def updated_at
+      @data.has_key?('updated_at') ? Time.parse(data['updated_at']) : nil
+    end
+    
+    def next #:nodoc:
+      nil
+    end
+    
+    def prev #:nodoc:
+      nil
+    end
+    
+    # Location of this object on teambox, used for updating
+    def url
+      nil
+    end
+    
+    # Reloads the resource from source data
+    #   @returns self
+    def reload
+      if @list.client && url
+        updated = @list.client.get(url) rescue nil
+        unless updated.nil?
+          @data = updated.data
+        end
+      end
+      self
+    end
+    
+    # Saves the resource to teambox
+    #   @returns true if saved
+    def save
+      if @list.client && url
+        updated = @list.client.put(url, @data) rescue nil
+        return true unless updated.nil?
+      end
+      false
+    end
+    
+    # Destroys the resource on teambox
+    def destroy
+      @list.client.delete(url) if @list.client && url
+      true
+    end
+    
+    def method_missing(method, *args, &block) #:nodoc:
+      @data.include?(method.to_s) ? @data[method.to_s] : super
+    end
+    
+    def inspect
+      "#<#{self.class} @data=#{@data.inspect} list=#{@list.object_id}>"
+    end
+  end
+end
+
+Dir[File.expand_path('models/*.rb', File.dirname(__FILE__))].each { |f| require f }

data/lib/teambox-client/teambox_oauth.rb

@@ -0,0 +1,37 @@
+module Teambox
+  # Methods used to authenticate with OAuth on teambox.com. Normally you won't have to call these.
+  module OAuth
+    attr_accessor :access_token
+    
+    # OAuth consumer required for authentication
+    def consumer
+      return nil if @auth[:oauth_app_id].nil?
+      @consumer ||= OAuth2::Client.new(@auth[:oauth_app_id], @auth[:oauth_app_secret], 
+                                       :site => consumer_url,
+                                       :access_token_path => consumer_url+'oauth/token',
+                                       :authorize_path => consumer_url+'oauth/authorize?response_type=code')
+    end
+    
+    def consumer_url
+      uri = URI.parse(self.class.base_uri)
+      uri.path = '/'
+      uri.to_s
+    end
+    
+    # Is the client authorized via OAuth?
+    def authorized?
+      !@access_token.nil?
+    end
+    
+    def authorize_from_request(verifier)
+      @access_token = consumer.web_server.get_access_token(verifier, :redirect_uri => @auth[:redirect_uri], :grant_type => 'authorization_code')
+      @auth[:oauth_token] = @access_token.token
+      @access_token
+    end
+    
+    # Authorizes the client from an existing OAuth token
+    def authorize_from_access
+      @access_token = ::OAuth2::AccessToken.new(nil, @auth[:oauth_token])
+    end
+  end
+end

data/lib/teambox-client.rb

@@ -0,0 +1,8 @@
+require "httparty"
+require "json"
+require "oauth2"
+require "uri"
+
+
+directory = File.expand_path(File.dirname(__FILE__))
+%w(teambox_oauth reference_list teambox result_set).each { |lib| require File.join(directory, 'teambox-client', lib) }

data/minmb-teambox-client.gemspec

@@ -0,0 +1,96 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "minmb-teambox-client"
+  s.version = "0.4.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Pablo Villalba", "James Urquhart", "Martin H\u{e4}ger"]
+  s.date = "2012-08-28"
+  s.description = "Provides methods to read and write to Teambox for ruby apps"
+  s.email = "martin.hager@minmb.se"
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    "Gemfile",
+    "Gemfile.lock",
+    "History",
+    "License",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "examples/conversation.rb",
+    "examples/task.rb",
+    "examples/users.rb",
+    "lib/teambox-client.rb",
+    "lib/teambox-client/models/activity.rb",
+    "lib/teambox-client/models/comment.rb",
+    "lib/teambox-client/models/conversation.rb",
+    "lib/teambox-client/models/divider.rb",
+    "lib/teambox-client/models/invitation.rb",
+    "lib/teambox-client/models/membership.rb",
+    "lib/teambox-client/models/note.rb",
+    "lib/teambox-client/models/organization.rb",
+    "lib/teambox-client/models/page.rb",
+    "lib/teambox-client/models/page_slot.rb",
+    "lib/teambox-client/models/person.rb",
+    "lib/teambox-client/models/project.rb",
+    "lib/teambox-client/models/task.rb",
+    "lib/teambox-client/models/task_list.rb",
+    "lib/teambox-client/models/teambox_data.rb",
+    "lib/teambox-client/models/upload.rb",
+    "lib/teambox-client/models/user.rb",
+    "lib/teambox-client/reference_list.rb",
+    "lib/teambox-client/result_set.rb",
+    "lib/teambox-client/teambox.rb",
+    "lib/teambox-client/teambox_oauth.rb",
+    "minmb-teambox-client.gemspec",
+    "spec/client_spec.rb",
+    "spec/conversation_spec.rb",
+    "spec/project_spec.rb",
+    "spec/resource_spec.rb",
+    "spec/result_set_spec.rb",
+    "spec/spec_helper.rb",
+    "spec/task_lists_spec.rb",
+    "spec/tasks_spec.rb"
+  ]
+  s.homepage = "http://github.com/minmb/teambox-ruby-client"
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.24"
+  s.summary = "A ruby gem wrapper for Teambox API"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<minmb-teambox-client>, [">= 0"])
+      s.add_development_dependency(%q<rake>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_runtime_dependency(%q<httparty>, ["~> 0.7.4"])
+      s.add_runtime_dependency(%q<oauth2>, ["~> 0.1.1"])
+      s.add_runtime_dependency(%q<json>, ["~> 1.5.1"])
+    else
+      s.add_dependency(%q<minmb-teambox-client>, [">= 0"])
+      s.add_dependency(%q<rake>, [">= 0"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<httparty>, ["~> 0.7.4"])
+      s.add_dependency(%q<oauth2>, ["~> 0.1.1"])
+      s.add_dependency(%q<json>, ["~> 1.5.1"])
+    end
+  else
+    s.add_dependency(%q<minmb-teambox-client>, [">= 0"])
+    s.add_dependency(%q<rake>, [">= 0"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<httparty>, ["~> 0.7.4"])
+    s.add_dependency(%q<oauth2>, ["~> 0.1.1"])
+    s.add_dependency(%q<json>, ["~> 1.5.1"])
+  end
+end
+

data/spec/client_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+
+describe Teambox::Client do
+  before do
+    @client = make_teambox_client
+  end
+  
+  it "should authenticate" do
+    @client.authenticated?.should == true
+  end
+  
+  it "should return the current user" do
+    user = @client.current_user
+    user.class.should == Teambox::User
+    user.username.should == 'frank'
+  end
+end

data/spec/conversation_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+describe Teambox::Conversation do
+  before do
+    @client = make_teambox_client
+    @project = @client.project('earthworks')
+  end
+  
+  it "should query conversations" do
+    @project.conversations.length.should_not == 0
+  end
+  
+  it "should make a conversation" do
+    conversation = @project.create_conversation({:name => 'Hello', :body => 'World'})
+    conversation.name.should == 'Hello'
+  end
+  
+  it "should list recent comments in a conversation" do
+    recent_comments = @project.conversations[0].recent_comments
+    recent_comments.length.should > 0
+    recent_comments.each {|c| c.class.should == Teambox::Comment}
+  end
+  
+  it "should list the first comment in a conversation" do
+    comment = @project.conversations[0].first_comment
+    comment.should_not == nil
+    comment.class.should == Teambox::Comment
+  end
+end

data/spec/project_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe Teambox::Project do
+  before do
+    @client = make_teambox_client
+  end
+  
+  it "should query a project" do
+    @client.project('earthworks').permalink.should == 'earthworks'
+  end
+end