workable 1.0.0 → 2.0.0rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9a4c28db1b5d41398db697d8d6e559a26524d952
-  data.tar.gz: 67a276520623daa50fe9d07d5b9ab49d736702c2
+  metadata.gz: d886522592c7473bc8fb058f56ea68a8b2d79585
+  data.tar.gz: c019b51b0a908a38ac418fd2ea8003f98c5e9ca5
 SHA512:
-  metadata.gz: c2994d3ef7f6d4d39ac0b76cac35aaf32e64096eed043502bb1363cb6983e8e8e33ffb9692b5ee090ff67d93e6ed79ab333d3f8a5add60935dd53ed082e74c79
-  data.tar.gz: 4273e9026eebd361f80beee5422c292ec4299f59c22b1ebdf23e1f94d84428df3a428f5560bce909e9c1438520d0100a059e17903f1ae50678cd8c53683aaa35
+  metadata.gz: 43d116e2475036166516674d0efff67bb5f8e13bd3f05bb0c63373ae91398df068d6190ac99f19f9bc662cd0d86755c7d3fbc752cafff4e177adbe9d888c1e4f
+  data.tar.gz: d9007195f31b8075e86a63a07bd3836a75ae2d6d1cc06e0ceccc9661212630f49e7a0f7e3c1d444f027f1824e7567afb7efada341279759fc405d7d77cb37de8

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 2.0.0rc1
+
+Date: 2015-11-02
+
+**Breaking change - switched to v3 API**
+
+https://workable.readme.io/docs/whats-new-in-v3
+
+- Collections returned by workable API are now paginated - that enforced introducing
+new `Workable::Collection` class that holds `data` (jobs/candidates) and reference
+to next page of results.
+
+- `jobs` method does not set default `stage` argument - please specify it explicitly!
+Also - now it accepts a hash as more parameters are available in v3 API
+
 ## 1.0.0
 
 Date: 2015-05-16

data/Gemfile

@@ -1,6 +1,6 @@
 source 'https://rubygems.org'
 
-#ruby=ruby-2.2.2
+# ruby=ruby-2.2.2
 
 # Specify your gem's dependencies in workable-client.gemspec
 gemspec

data/Guardfile

@@ -1,7 +1,7 @@
 directories %w(lib spec)
 
-guard :rspec, cmd: "rspec" do
+guard :rspec, cmd: 'rspec' do
   watch(%r{^spec/.+_spec\.rb$})
-  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
-  watch(%r{spec/(spec_helper|fixtures)\.rb$})  { "spec" }
+  watch(%r{^lib/(.+)\.rb$}) { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch(%r{spec/(spec_helper|fixtures)\.rb$}) { 'spec' }
 end

data/README.md

@@ -8,7 +8,7 @@
 
 Dead-simple Ruby API client for [workable.com][1]. No extra runtime dependencies. Ruby >= 1.9.3.
 
-Uses v2 API provided by workable.
+Uses v3 API provided by workable.
 
 ## Installation
 
@@ -28,18 +28,17 @@ Or install it yourself as:
 
 ## Usage
 
-Internal interface / api is in early stage, so far you can:
-- fetch jobs
-- fetch job details
-- fetch candidates for given job
+Gem covers all endpoints mentioned in official v3 workable API documentation (https://workable.readme.io/docs/).
 
 ### Example
 
+For detailed documentation please refer to: http://www.rubydoc.info/gems/workable
+
 ``` ruby
 client = Workable::Client.new(api_key: 'api_key', subdomain: 'your_subdomain')
 
 # takes optional phase argument (string): 'published' (default), 'draft', 'closed' or 'archived'
-client.jobs # => Array of hashes
+client.jobs # => Workable::Collection
 
 shortcode = client.jobs.first["shortcode"]
 

data/Rakefile

@@ -1,10 +1,11 @@
-require "rspec/core/rake_task"
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
 
 RSpec::Core::RakeTask.new('spec')
 task default: :spec
 
 task :console do
-  sh "irb -r ./lib/workable.rb"
+  sh 'irb -r ./lib/workable.rb'
 end
 
 task c: :console

data/lib/workable.rb

@@ -3,11 +3,14 @@ require 'uri'
 require 'net/http'
 require 'date'
 require 'ostruct'
+require 'cgi'
 
-require_relative "workable/version"
-require_relative "workable/errors"
-require_relative "workable/client"
+require_relative 'workable/version'
+require_relative 'workable/errors'
+require_relative 'workable/client'
+require_relative 'workable/transformation'
+require_relative 'workable/collection'
 
 module Workable
-  API_VERSION = "2".freeze
+  API_VERSION = 3
 end

data/lib/workable/client.rb

@@ -1,13 +1,12 @@
 module Workable
   class Client
-
     # set access to workable and data transformation methods
     #
     # @param options [Hash]
     # @option options :api_key   [String] api key for workable
     # @option options :subdomain [String] company subdomain in workable
     # @option options :transform_to [Hash<Symbol: Proc>] mapping of transformations for data
-    #    available transformations: [:job, :candidate, :question, :stage]
+    #    available transformations: [:job, :candidate, :question, :stage, :recruiter, :member]
     #    when no transformation is given raw Hash / Array data is returned
     #
     # @example transformation for candidates using `MyApp::Candidate.find_and_update_or_create`
@@ -29,60 +28,103 @@ module Workable
     #      }
     #    )
     def initialize(options = {})
-      @api_key   = options.fetch(:api_key)   { fail Errors::InvalidConfiguration, "Missing api_key argument"   }
-      @subdomain = options.fetch(:subdomain) { fail Errors::InvalidConfiguration, "Missing subdomain argument" }
-      @transform_to   = options[:transform_to]   || {}
-      @transform_from = options[:transform_from] || {}
+      @api_key   = options.fetch(:api_key)   { configuration_error 'Missing api_key argument'   }
+      @subdomain = options.fetch(:subdomain) { configuration_error 'Missing subdomain argument' }
+      @transform_to   = Transformation.new(options[:transform_to])
+      @transform_from = Transformation.new(options[:transform_from])
+    end
+
+    # return information about your account
+    def about
+      get_request('')
+    end
+
+    # returns a collection of your account members
+    def members
+      @transform_to.apply(:member, get_request('members')['members'])
+    end
+
+    # returns a collection of your account external recruiters
+    def recruiters
+      @transform_to.apply(:recruiter, get_request('recruiters')['recruiters'])
+    end
+
+    # returns a collection of your recruitment pipeline stages
+    def stages
+      @transform_to.apply(:stage, get_request('stages')['stages'])
     end
 
-    # request jobs of given type
-    # @param type [String] type of jobs to fetch, `published` by default
-    def jobs(type = 'published')
-      transform_to(:job, get_request("jobs?phase=#{type}")['jobs'])
+    # request posted jobs
+    # @option params [Hash] optional filter parameters
+    # @option params :state [String] Returns jobs with the current state. Possible values (draft, published, archived & closed)
+    # @option params :limit [Integer] Specifies the number of jobs to try and retrieve per page
+    # @option params :since_id [String] Returns results with an ID more than or equal to the specified ID.
+    # @option params :max_id [String] Returns results with an ID less than or equal to the specified ID.
+    # @option params :created_after [Timestamp|Integer] Returns results created after the specified timestamp.
+    # @option params :updated_after [Timestamp|Integer] Returns results updated after the specified timestamp.
+    def jobs(params = {})
+      build_collection('jobs', :job, 'jobs', params)
     end
 
     # request detailed information about job
     # @param shortcode [String] job short code
     def job_details(shortcode)
-      transform_to(:job, get_request("jobs/#{shortcode}"))
+      @transform_to.apply(:job, get_request("jobs/#{shortcode}"))
+    end
+
+    # list of questions for job
+    # @param shortcode [String] job short code
+    def job_questions(shortcode)
+      @transform_to.apply(:question, get_request("jobs/#{shortcode}/questions")['questions'])
+    end
+
+    # return a collection of job's members
+    # @param shortcode [String] job short code
+    def job_members(shortcode)
+      @transform_to.apply(:member, get_request("jobs/#{shortcode}/members")['members'])
+    end
+
+    # return a collection of the job's external recruiters
+    # @param shortcode [String] job short code
+    def job_recruiters(shortcode)
+      @transform_to.apply(:recruiter, get_request("jobs/#{shortcode}/recruiters")['recruiters'])
     end
 
     # list candidates for given job
     # @param  shortcode [String] job shortcode to select candidates from
-    # @param  options   [Hash]   extra options like `stage_slug` or `limit`
-    # @option options :stage [String]        optional stage slug, if not given candidates are listed for all stages
-    # @option options :limit [Number|String] optional limit of candidates to download, if not given all candidates are listed
-    def job_candidates(shortcode, options = {})
-      url = build_job_candidates_url(shortcode, options)
-      transform_to(:candidate, get_request(url)['candidates'])
+    # @param  params [Hash]   extra options like `state` or `limit`
+    # @option params :state [String]        optional state slug, if not given candidates are listed for all stages
+    # @option params :limit [Number|String] optional limit of candidates to download, if not given all candidates are listed
+    # @option params :since_id [String] Returns results with an ID more than or equal to the specified ID.
+    # @option params :max_id [String] Returns results with an ID less than or equal to the specified ID.
+    # @option params :created_after [Timestamp|Integer] Returns results created after the specified timestamp.
+    # @option params :updated_after [Timestamp|Integer] Returns results updated after the specified timestamp.
+    def job_candidates(shortcode, params = {})
+      build_collection("jobs/#{shortcode}/candidates", :candidate, 'candidates', params)
     end
 
-    # list of questions for job
-    # @param shortcode [String] job short code
-    def job_questions(shortcode)
-      transform_to(:question, get_request("jobs/#{shortcode}/questions")['questions'])
+    # return the full object of a specific candidate
+    # @param shortcode [String] job shortcode to select candidate from
+    # @param id [String] candidates's id
+    def job_candidate(shortcode, id)
+      @transform_to.apply(:candidate, get_request("jobs/#{shortcode}/candidates/#{id}")['candidate'])
     end
 
     # create new candidate for given job
     # @param candidate  [Hash] the candidate data as described in
-    #    http://resources.workable.com/add-candidates-using-api
+    #    https://workable.readme.io/docs/job-candidates-create
     #    including the `{"candidate"=>{}}` part
     # @param shortcode  [String] job short code
     # @param stage_slug [String] optional stage slug
     # @return [Hash] the candidate information without `{"candidate"=>{}}` part
     def create_job_candidate(candidate, shortcode, stage_slug = nil)
-      shortcode = "#{shortcode}/#{stage_slug}" unless stage_slug.nil?
-      transform_to(:candidate, post_request("jobs/#{shortcode}/candidates", candidate)["candidate"])
-    end
+      shortcode = "#{shortcode}/#{stage_slug}" if stage_slug
 
-    # list of stages defined for company
-    def stages
-      transform_to(:stage, get_request("stages")['stages'])
-    end
+      response = post_request("jobs/#{shortcode}/candidates") do |request|
+        request.body = @transform_from.apply(:candidate, candidate).to_json
+      end
 
-    # list of external recruiters for company
-    def recruiters
-      transform_to(:stage, get_request("recruiters")['recruiters'])
+      @transform_to.apply(:candidate, response['candidate'])
     end
 
     private
@@ -91,28 +133,30 @@ module Workable
 
     # build the url to api
     def api_url
-      "https://www.workable.com/spi/v%s/accounts/%s" % [Workable::API_VERSION, subdomain]
+      'https://www.workable.com/spi/v%s/accounts/%s' % [Workable::API_VERSION, subdomain]
     end
 
     # do the get request to api
-    def get_request(url)
-      do_request(url, Net::HTTP::Get)
+    def get_request(url, params = {})
+      params = URI.encode_www_form(params.keep_if { |k, v| k && v })
+      full_url = params.empty? ? url : [url, params].join('?')
+      do_request(full_url, Net::HTTP::Get)
     end
 
     # do the post request to api
-    def post_request(url, data)
+    def post_request(url)
       do_request(url, Net::HTTP::Post) do |request|
-        request.body = transform_from(:candidate, data).to_json
+        yield(request) if block_given?
       end
     end
 
     # generic part of requesting api
-    def do_request(url, type, &block)
+    def do_request(url, type, &_block)
       uri = URI.parse("#{api_url}/#{url}")
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = true
 
-      request  = type.new(uri.request_uri, headers)
+      request = type.new(uri.request_uri, headers)
       yield request if block_given?
       response = http.request(request)
 
@@ -127,28 +171,26 @@ module Workable
       when 200...300 # handled with response
         JSON.parse(response.body)
       when 401
-        raise Errors::NotAuthorized, JSON.parse(response.body)["error"]
+        fail Errors::NotAuthorized, JSON.parse(response.body)['error']
       when 404
-        raise Errors::NotFound, JSON.parse(response.body)["error"]
+        fail Errors::NotFound, JSON.parse(response.body)['error']
       when 422
         handle_response_422(response)
       when 503
-        raise Errors::RequestToLong, response.body
+        fail Errors::RequestToLong, response.body
       else
-        raise Errors::InvalidResponse, "Response code: #{response.code} message: #{response.body}"
+        fail Errors::InvalidResponse, "Response code: #{response.code} message: #{response.body}"
       end
     end
 
     def handle_response_422(response)
       data = JSON.parse(response.body)
-      if
-        data["validation_errors"] &&
-        data["validation_errors"]["email"] &&
-        data["validation_errors"]["email"].include?("candidate already exists")
-      then
-        raise Errors::AlreadyExists, data["error"]
+      if data['validation_errors'] &&
+         data['validation_errors']['email'] &&
+         data['validation_errors']['email'].include?('candidate already exists')
+        fail Errors::AlreadyExists, data['error']
       else
-        raise Errors::NotFound, data["error"]
+        fail Errors::NotFound, data['error']
       end
     end
 
@@ -158,35 +200,10 @@ module Workable
         'Accept'        => 'application/json',
         'Authorization' => "Bearer #{api_key}",
         'Content-Type'  => 'application/json',
-        'User-Agent'    => 'Workable Ruby Client',
+        'User-Agent'    => 'Workable Ruby Client'
       }
     end
 
-    # build url for fetching job candidates
-    # @param  shortcode [String] job shortcode to select candidates from
-    # @param  options   [Hash]   extra options like `stage_slug` or `limit`
-    # @option options :stage_slug [String]        optional stage slug, if not given candidates are listed for all stages
-    # @option options :limit      [Number|String] optional limit of candidates to download, if not given all candidates are listed
-    def build_job_candidates_url(shortcode, options)
-      if (stage_slug = options.delete(:stage))
-      then stage_slug = "/#{stage_slug}"
-      end
-      params =
-      if options.empty?
-      then ""
-      else "?#{options.map{|k,v| "#{k}=#{v}"}.join("&")}"
-      end
-      "jobs/#{shortcode}#{stage_slug}/candidates#{params}"
-    end
-
-    # transform result using given method if defined
-    # @param type [Symbol] type of the transformation, one of `[:job, :candidate, :question, :stage]`
-    # @param result [Hash|Array|nil] the value to transform, can be nothing, `Hash` of values or `Array` of `Hash`es
-    # @return transformed result if transformation exists for type, raw result otherwise
-    def transform_to(type, result)
-      transform(@transform_to[type], result)
-    end
-
     # transform input using given method if defined
     # @param type [Symbol] type of the transformation, only `[:candidate]` supported so far
     # @param result [Hash|Array|nil] the value to transform, can be nothing, `Hash` of values or `Array` of `Hash`es
@@ -195,22 +212,20 @@ module Workable
       transform(@transform_from[type], input)
     end
 
-    # selects transformation strategy based on the inputs
-    # @param transformation [Method|Proc|nil] the transformation to perform
-    # @param data           [Hash|Array|nil]  the data to transform
-    # @return               [Object|nil]
-    #    results of the transformation if given, raw data otherwise
-    def transform(transformation, data)
-      return data unless transformation
-      case data
-      when nil
-        data
-      when Array
-        data.map{|datas| transformation.call(datas) }
-      else
-        transformation.call(data)
-      end
+    def build_collection(url, transform_mapping, root_key, params = {})
+      url = url.gsub(/#{api_url}\/?/, '')
+      response = get_request(url, params)
+
+      Collection.new(
+        @transform_to.apply(transform_mapping, response[root_key]),
+        method(__callee__),
+        transform_mapping,
+        root_key,
+        response['paging'])
     end
 
+    def configuration_error(message)
+      fail Errors::InvalidConfiguration, message
+    end
   end
 end

data/lib/workable/collection.rb

@@ -0,0 +1,29 @@
+module Workable
+  class Collection
+    extend Forwardable
+    def_delegators :@data, :size, :each, :[], :map, :first
+
+    attr_reader :data
+
+    def initialize(data, next_page_method, transform_mapping, root_key, paging = nil)
+      @data = data
+
+      if paging
+        @next_page = paging['next']
+        @next_page_method = next_page_method
+        @transform_mapping = transform_mapping
+        @root_key = root_key
+      end
+    end
+
+    def next_page?
+      !! @next_page
+    end
+
+    def fetch_next_page
+      return unless next_page?
+
+      @next_page_method.call(@next_page, @transform_mapping, @root_key)
+    end
+  end
+end

data/lib/workable/errors.rb

@@ -1,11 +1,11 @@
 module Workable
   module Errors
-    class WorkableError        < StandardError; end
+    class WorkableError < StandardError; end
     class InvalidConfiguration < WorkableError; end
-    class NotAuthorized        < WorkableError; end
-    class InvalidResponse      < WorkableError; end
-    class NotFound             < WorkableError; end
-    class AlreadyExists        < WorkableError; end
-    class RequestToLong        < WorkableError; end
+    class NotAuthorized < WorkableError; end
+    class InvalidResponse < WorkableError; end
+    class NotFound < WorkableError; end
+    class AlreadyExists < WorkableError; end
+    class RequestToLong < WorkableError; end
   end
 end