freelancer 0.1.0

data/lib/freelancer/api/profile.rb

@@ -0,0 +1,30 @@
+module Freelancer
+  module API
+    module Profile
+      module InstanceMethods
+
+        # Retrieve profile information for the current user
+        def account_details
+
+          result = api_get("/Profile/getAccountDetails.json")
+          ::Freelancer::Models::User.parse(result, :shift => :"json-result")
+          
+        end
+
+        # Retrieve profile information about a specific user
+        #
+        # Valid parameters are:
+        #   - user_id: the user id to retrieve profile for
+        def profile_info(*args)
+
+          params = extract_params(args)
+
+          result = api_get("/Profile/getProfileInfo.json", { :userid => params[:user_id] })
+          ::Freelancer::Models::User.parse(result, :shift => :"json-result")
+
+        end
+
+      end
+    end
+  end
+end

data/lib/freelancer/api/project.rb

@@ -0,0 +1,133 @@
+module Freelancer
+  module API
+    module Project
+      module InstanceMethods
+
+        # Search for projects using a specified set of criterias.
+        #
+        # Valid parameters are:
+        #   - featured: if only featured projects should be returned
+        #   - non_public: if only non-public projects should be returned
+        #   - keyword: the keyword to use for searching
+        #   - job: a specific job type, or an array of job types, to search for
+        #   - status: the project status to filter projects by
+        #   - minimum_budget: the minimum budget to return projects by
+        #   - maximum_budget: the maximum budget to return projects by
+        #   - full_time: if only full time projects should be returned
+        #   - trial: if only trial projects should be returned
+        #   - gold_members_only: if only gold member only-projects should be returned
+        #   - duration: the bid end duration for the project (submitdate (default), bid_enddate, id or state)
+        #   - count: the number of results to return (defaults to 50)
+        #   - page: the page to retrieve (defaults to 0)
+        def project_search(*args)
+
+          params = extract_params(args)
+
+          # Handle the job attribute, make sure it's an array and not set to nil to
+          # simplify the handling below.
+          params[:job] ||= []
+          params[:job] = params[:job].to_a unless params[:job].is_a?(Array)
+
+          # Delete some boolean data from the params if the values are set to fault,
+          # since that's the default already
+          [ :featured, :non_public, :full_time, :trial, :gold_members_only ].each do |k|
+            params.delete(k) if params.key?(k) && params[k] == false
+          end
+
+          # Execute the service call
+          result = api_get("/Project/searchProjects.json", build_api_params({
+            :isfeatured => params[:featured],
+            :isnonpublic => params[:non_public],
+            :searchkeyword => params[:keyword],
+            :searchjobtypecsv => params[:job].join(","),
+            :status => params[:status],
+            :budgetmin => params[:minimum_budget],
+            :budgetmax => params[:maximum_budget],
+            :isfulltime => params[:full_time],
+            :istrial => params[:trial],
+            :isgoldmembersonly => params[:gold_members_only],
+            :bidendsduration => params[:duration],
+            :count => params[:count],
+            :page => params[:page]
+          }))
+
+          # Parse and return the response
+          ::Freelancer::Models::Project.parse_collection(result, :shift => [ :"json-result", :items ])
+          
+        end
+
+        # Retrieve the available project type fees
+        def project_fees
+
+          result = api_get("/Project/getProjectFees.json")
+          ::Freelancer::Models::ProjectFee.parse_collection(result, :shift => [ :"json-result", :items ])
+
+        end
+
+        # Retrieve information about a project
+        #
+        # Valid parameters are:
+        #   - project_id: the id of the project to retrieve
+        def project_details(*args)
+
+          params = extract_params(args)
+
+          # Execute the service call
+          result = api_get("/Project/getProjectDetails.json", build_api_params({
+            :projectid => params[:project_id]
+          }))
+
+          # Parse and return the response
+          ::Freelancer::Models::Project.parse(result, :shift => :"json-result")
+          
+        end
+
+        # Retrieve the bids for a project
+        #
+        # Valid parameters are:
+        #   - project_id: the id of the project to retrieve bids for
+        def project_bids(*args)
+
+          params = extract_params(args)
+
+          # Execute the service call
+          result = api_get("/Project/getBidsDetails.json", build_api_params({
+            :projectid => params[:project_id]
+          }))
+
+          # Parse and return the response
+          ::Freelancer::Models::Bid.parse_collection(result, :shift => [ :"json-result", :items ])
+          
+        end
+
+        # Retrieve the public messages for a project
+        #
+        # Valid parameters are:
+        #   - project_id: the id of the project to retrieve bids for
+        def public_messages(*args)
+
+          params = extract_params(args)
+
+          # Execute the service call
+          result = api_get("/Project/getPublicMessages.json", build_api_params({
+            :projectid => params[:project_id]
+          }))
+
+          # Parse and return the response
+          ::Freelancer::Models::Message.parse_collection(result, :shift => [ :"json-result", :items ])
+
+        end
+
+        # Retrieve the project budget configurations
+        def project_budgets
+
+          result = api_get("/Project/getProjectBudgetConfig.json")
+          ::Freelancer::Models::ProjectBudget.parse_collection(result, :shift => [ :"json-result", :items ])
+          
+        end
+
+      end
+
+    end
+  end
+end

data/lib/freelancer/api/user.rb

@@ -0,0 +1,86 @@
+module Freelancer
+  module API
+    module User
+      module InstanceMethods
+
+        # Search for users
+        #
+        # Valid parameters are:
+        #   - username: the username to search for
+        #   - expertise: a specific expertise, or an array of expertises, to search for
+        #   - country: a specific country, or an array of countries, to search for
+        #   - rating: the minimum rating to search for
+        #   - count: the number of results to return (defaults to 50)
+        #   - page: the page to retrieve (defaults to 0)
+        def user_search(*args)
+
+          params = extract_params(args)
+
+          # Handle the expertise and country attributes. Make sure they're an array and not set
+          # to nil to simplify the handling below.
+          params[:country] ||= []
+          params[:country] = params[:country].to_a unless params[:country].is_a?(Array)
+          params[:expertise] ||= []
+          params[:expertise] = params[:expertise].to_a unless params[:expertise].is_a?(Array)
+
+          # Execute the service call
+          result = api_get("/User/getUsersBySearch.json", build_api_params({
+            :username => params[:username],
+            :expertise_csv => params[:expertise].join(","),
+            :country_csv => params[:country].join(","),
+            :rating => params[:rating],
+            :count => params[:count],
+            :page => params[:page]
+          }))
+
+          # Parse and return the response
+          ::Freelancer::Models::User.parse_collection(result, :shift => [ :"json-result", :items ])
+
+        end
+
+        # Search for users
+        #
+        # Valid parameters are:
+        #   - username: the username to list feedback for
+        #   - user_id: the user id to list feedback for
+        #   - type: the type of feedback to show ("P" = provider only, "B" = buyer only, "A" = all (default))
+        def user_feedback(*args)
+
+          params = extract_params(args)
+
+          # Execute the service call
+          result = api_get("/User/getUserFeedback.json", build_api_params({
+            :username => params[:username],
+            :userid => params[:user_id],
+            :type => params[:type]
+          }))
+
+          # Parse and return the response
+          ::Freelancer::Models::Review.parse_collection(result, :shift => [ :user, :totalreviews, :items ])
+
+        end
+
+        # Retrieve user details for a specific user
+        #
+        # Valid parameters are:
+        #   - username: the username to retrieve details for
+        #   - user_id: the user id to retrieve details for
+        def user_details(*args)
+
+          params = extract_params(args)
+
+          # Execute the service call
+          result = api_get("/User/getUserDetails.json", build_api_params({
+            :username => params[:username],
+            :userid => params[:user_id]
+          }))
+
+          # Parse and return the response
+          ::Freelancer::Models::User.parse(result, :shift => :user)
+          
+        end
+
+      end
+    end
+  end
+end

data/lib/freelancer/client.rb

@@ -0,0 +1,152 @@
+module Freelancer
+  class Client
+    
+    extend API
+    
+    # Load the different API plugins
+    api API::User
+    api API::Job
+    api API::Profile
+    api API::Employer
+    api API::Freelancer
+    api API::Common
+    api API::Payment
+    api API::Notification
+    api API::Project
+    api API::Message
+
+    attr_reader :consumer_token, :consumer_secret, :consumer_options
+    
+    # Initialize a new Freelancer API client
+    def initialize(consumer_token, consumer_secret, consumer_options = {})
+      
+      default_options = {
+        :request_token_path => "/RequestRequestToken/requestRequestToken.xml",
+        :authorize_url => "http://www.sandbox.freelancer.com/users/api-token/auth.php",
+        :access_token_path => "/RequestAccessToken/requestAccessToken.xml",
+        :scheme => :query_string,
+        :http_method => :get
+      }
+      
+      @consumer_token, @consumer_secret, @consumer_options = consumer_token, consumer_secret, consumer_options.merge(default_options)
+      @api_endpoint = "http://api.sandbox.freelancer.com"
+    
+    end
+    
+    # Get the current oAuth consumer instance
+    def consumer
+      @consumer ||= ::OAuth::Consumer.new(consumer_token, consumer_secret, { :site => @api_endpoint }.merge(consumer_options))
+    end
+    
+    # Set the callback URL for an oAuth request
+    def set_callback_url(url)
+      clear_request_token
+      request_token :oauth_callback => url
+    end
+    
+    # Get the current oAuth request token
+    def request_token(options = {})
+      @request_token_instance ||= consumer.get_request_token(options)
+    end
+    
+    # Authorize a user from an oAuth request
+    def authorize_from_request(request_token, request_secret, verifier)
+      
+      request_token = ::OAuth::RequestToken.new(consumer, request_token, request_secret)
+      access_token = request_token.get_access_token(:oauth_verifier => verifier)
+      @access_token, @access_secret = access_token.token, access_token.secret
+
+    end
+    
+    # Get the current oAuth access token
+    def access_token
+      @access_token_instance ||= ::OAuth::AccessToken.new(consumer, @access_token, @access_secret)
+    end
+    
+    # Authorize a user from an oAuth access token
+    def authorize_from_access(access_token, access_secret)
+      @access_token, @access_secret = access_token, access_secret
+    end
+    
+    # Execute a GET-request for the specified API method
+    def api_get(method, options = {})
+      response = access_token.get(to_uri(method, options))
+      raise_api_errors!(response)
+      return response.body
+    end
+    
+    # Execute a GET-requset for the specified API method and return the raw
+    # result.
+    def api_get_raw(method, options = {})
+      response = access_token.get(to_uri(method, options))
+      raise_api_errors!(response)
+      response.body
+    end
+    
+    # Execute a POST-request for the specified API method
+    # TODO: Finish this method, it should probably return some JSON decoded
+    # string.
+    def api_post(method, body)
+      response = access_token.post(method, body)
+      response.body
+    end
+
+    private
+
+    # Extract params from an array of arguments. Copied from ActiveSupport.
+    def extract_params(args)
+      args.last.is_a?(Hash) ? args.last : {}
+    end
+
+    # Build a hash of parameters based on the arguments, stripping out any blank
+    # arguments.
+    def build_api_params(params)
+      params.reject { |key, value| value.nil? || value == "" }
+    end
+    
+    # Clear the current oAuth request token
+    def clear_request_token
+      @request_token_instance = nil
+    end
+    
+    # Raise an error for the specified API method response if any
+    def raise_api_errors!(response)
+      
+      case response.code.to_i
+      when 1..199
+        raise "Response code #{response.code}: #{response}"
+      when 201..503
+        raise "Response code: #{response.code}: #{response}"
+      end
+      
+    end
+    
+    # Create a URI from the specified method and options
+    def to_uri(method, options)
+      
+      uri = URI.parse(method)
+      unless options.nil? || options.empty?
+        uri.query = to_query(options)
+      end
+      
+      return uri.to_s
+      
+    end
+    
+    # Convert a hash to a proper query string
+    def to_query(params)
+      params.inject([]) do |collection, options|
+        options[1] = URI.escape(options[1]) if options[1].is_a?(String) && !options[1].nil?
+        collection << "#{options[0]}=#{options[1]}"
+        collection
+      end * "&"
+    end
+    
+    # Decode any HTML entities in the given string
+    def html_decode(str)
+      encoder = HTMLEntities.new
+      encoder.decode(str)
+    end
+    
+  end
+end

data/lib/freelancer/extensions/hash.rb

@@ -0,0 +1,11 @@
+class Hash
+
+  # Symbolize the keys in the hash. Copied from ActiveSupport's Core Extensions.
+  def symbolize_keys
+    inject({}) do |options, (key, value)|
+      options[(key.to_sym rescue key) || key] = value
+      options
+    end
+  end
+
+end

data/lib/freelancer/models/address.rb

@@ -0,0 +1,46 @@
+module Freelancer
+  module Models
+    class Address
+
+      include JSONMapper
+
+      # The first streetname of the address
+      #
+      # Provided from:
+      #   - /Profile/getAccountDetails.json
+      json_attribute :street_name, :addressline1, String
+
+      # The second streetname of the address
+      #
+      # Provided from:
+      #   - /Profile/getAccountDetails.json
+      json_attribute :street_name_2, :addressline2, String
+
+      # The postal code of the address
+      #
+      # Provided from:
+      #   - /Profile/getAccountDetails.json
+      json_attribute :postal_code, :postalcode, String
+
+      # The city part of the address
+      #
+      # Provided from:
+      #   - /User/getUserDetails.json
+      json_attribute :city, String
+
+
+      # The state part of the address
+      #
+      # Provided from:
+      #   - /Profile/getAccountDetails.json
+      json_attribute :state, String
+
+      # The country the address is located in
+      # 
+      # Provided from:
+      #   - /User/getUserDetails.json
+      json_attribute :country, String
+
+    end
+  end
+end