workable 0.2.0 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7eaebf59a51c6219ca5f278a91b99226b043fa1d
-  data.tar.gz: f41c7493529160c2d7e134b0aeb1d3284b5218e2
+  metadata.gz: a09a961ce4873bd3a9f5d5ca68f74a7332af0c71
+  data.tar.gz: 613aae7f8c29374abcb0fd1b6dfb1043d4dfdeec
 SHA512:
-  metadata.gz: 840612f71285030a314ab414b8facd077e0cbc8eac8076353a8ab4a4b835c954c9000d9454ceda93b19b0cf97b7154fad33e95ff109a27f2d72196217b3a8cd7
-  data.tar.gz: 3231f81122c3170a0d461eed5c95733b0cd9fe85381ced8834eacb1988d873bcf65e7e5497d21f1e5bdab5e72b6eec72afd05bccb6837b63c80c4ff924cb6172
+  metadata.gz: 58fff5454c71ac7eaed87a20f34273d66a5ba86050686c8c28c95fbb0b3d128073fb41904cbb63d81f05bdb5ad5ed1c7b9ed2bbb920b51f585947b1dea8a66de
+  data.tar.gz: 2bc4952238a7c751c75480d7f70898a51b73a6cf6bee812f65f0a373807c00b8f4eec67327f24f1a763c2016cd873f1e051383237f187ba6f72f6defec76b00c

data/.gitignore

@@ -7,6 +7,7 @@
 /pkg/
 /spec/reports/
 /tmp/
+/*.gem
 *.bundle
 *.so
 *.o

data/Gemfile

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

data/Guardfile

@@ -0,0 +1,7 @@
+directories %w(lib spec)
+
+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" }
+end

data/README.md

@@ -33,22 +33,28 @@ Internal interface / api is in early stage, so far you can:
 - fetch job details
 - fetch candidates for given job
 
-**Example:**
+### Example
 
 ``` 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 # => [#<Workable::Job>, #<Workable::Job>]
+client.jobs # => Array of hashes
 
-shortcode = 'job_shortcode'
+shortcode = client.jobs.first["shortcode"]
 
 # API queries are not cached (at all) - it's up to you to cache results one way or another
 
-client.stages # => Array of hashes
-client.job_details(shortcode)   # => #<Workable::Job>
-client.job_questions(shortcode) # => Array of hashes
-client.job_candidates(shortcode, stage_slug) # => Array of hashes (skip stage_slug for all stages)
+client.stages     # => Array of hashes
+client.recruiters # => Array of hashes
+client.job_details(shortcode)    # => Hash
+client.job_questions(shortcode)  # => Array of hashes
+client.job_candidates(shortcode, stage_slug) # => Array of hashes (stage_slug is optional)
+
+# Adding candidates - candidate is a Hash as described in:
+#   http://resources.workable.com/add-candidates-using-api
+
+client.create_job_candidate(candidate, shortcode, stage_slug) # => Hash (stage_slug is optional)
 
 # Possible errors (each one inherits from Workable::Errors::WorkableError)
 Workable::Errors::InvalidConfiguration # missing api_key / subdomain
@@ -58,14 +64,39 @@ Workable::Errors::NotFound        # 404 from workable
 Workable::Errors::RequestToLong   # When the requested result takes to long to calculate, try limiting your query
 ```
 
-## Missing/Todo
+## Transformations
+
+When creating `Client` you can specify extra methods/`Proc`s for
+automated transformation of results and input.
+
+### Example
+
+```ruby
+client = Workable::Client.new(
+  api_key: 'api_key',
+  subdomain: 'your_subdomain'
+  transform_to: {
+    candidate: OpenStruct.method(:new)
+  }
+  transform_from: {
+    candidate: Proc.new { |input| input.to_h }
+  }
+)
+```
+
+The first transformation `to` will make the `Client` return
+`OpenStruct.new(result)` instead of just plain `result` everywhere where
+candidate is expected. In case of Arrays the transformation will be
+applied to every element.
 
-Pull requests are welcomed. So far this gem does not provide:
+The second transformation `from` will expect an instance of `OpenStruct`
+instead of raw data and will execute the `to_h` on the instance before
+sending it to workable API.
 
-- candidates import
-- some sane way for parsing candidates json response
+The rest of result will be returned as `Array`s/`Hash`es,
+no transformation will be applied if not defined - raw data will be
+returned.
 
-_(Personally I don't really need/use it)_
 
 ## Contributing
 

data/Rakefile

@@ -1,4 +1,3 @@
-require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new('spec')

data/lib/workable/client.rb

@@ -1,74 +1,182 @@
 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]
+    #    when no transformation is given raw Hash / Array data is returned
+    #
+    # @example transformation for candidates using `MyApp::Candidate.find_and_update_or_create`
+    #    client = Workable::Client.new(
+    #      api_key: 'api_key',
+    #      subdomain: 'your_subdomain',
+    #      transform_to: {
+    #        candidate: &MyApp::Candidate.method(:find_and_update_or_create)
+    #      }
+    #    )
+    #
+    # @example Linkedin gem style with Mash
+    #   require "hashie"
+    #    client = Workable::Client.new(
+    #      api_key: 'api_key',
+    #      subdomain: 'your_subdomain',
+    #      transform_to: {
+    #        candidate: &Hashie::Mash.method(:new)
+    #      }
+    #    )
     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] || {}
     end
 
+    # request jobs of given type
+    # @param type [String] type of jobs to fetch, `published` by default
     def jobs(type = 'published')
-      get_request("jobs?phase=#{type}")['jobs'].map do |params|
-        Job.new(params)
-      end
+      transform_to(:job, get_request("jobs?phase=#{type}")['jobs'])
     end
 
+    # request detailed information about job
+    # @param shortcode [String] job short code
     def job_details(shortcode)
-      Job.new(get_request"jobs/#{shortcode}")
+      transform_to(:job, get_request("jobs/#{shortcode}"))
     end
 
+    # list candidates for given job
+    # @param shortcode  [String]     job shortcode to select candidates from
+    # @param stage_slug [String|nil] optional stage slug, if not given candidates are listed for all stages
     def job_candidates(shortcode, stage_slug = nil)
       shortcode = "#{shortcode}/#{stage_slug}" unless stage_slug.nil?
-      get_request("jobs/#{shortcode}/candidates")['candidates']
+      transform_to(:candidate, get_request("jobs/#{shortcode}/candidates")['candidates'])
     end
 
+    # list of questions for job
+    # @param shortcode [String] job short code
     def job_questions(shortcode)
-      get_request("jobs/#{shortcode}/questions")['questions']
+      transform_to(:question, get_request("jobs/#{shortcode}/questions")['questions'])
+    end
+
+    # create new candidate for given job
+    # @param candidate  [Hash] the candidate data as described in
+    #    http://resources.workable.com/add-candidates-using-api
+    #    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
 
+    # list of stages defined for company
     def stages
-      get_request("stages")['stages']
+      transform_to(:stage, get_request("stages")['stages'])
+    end
+
+    # list of external recruiters for company
+    def recruiters
+      transform_to(:stage, get_request("recruiters")['recruiters'])
     end
 
     private
 
     attr_reader :api_key, :subdomain
 
+    # build the url to api
     def api_url
       "https://www.workable.com/spi/v%s/accounts/%s" % [Workable::API_VERSION, subdomain]
     end
 
+    # do the get request to api
     def get_request(url)
-      uri = URI.parse("#{api_url}/#{url}")
+      do_request(url, Net::HTTP::Get)
+    end
+
+    # do the post request to api
+    def post_request(url, data)
+      do_request(url, Net::HTTP::Post) do |request|
+        request.body = transform_from(:candidate, data).to_json
+      end
+    end
 
+    # generic part of requesting api
+    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  = Net::HTTP::Get.new(uri.request_uri, headers)
+      request  = type.new(uri.request_uri, headers)
+      yield request if block_given?
       response = http.request(request)
 
-      validate!(response)
-
-      JSON.parse(response.body)
+      parse!(response)
     end
 
-    def validate!(response)
+    # parse the api response
+    def parse!(response)
       case response.code.to_i
+      when 204, 205
+        nil
+      when 200...300
+        JSON.parse(response.body)
       when 401
         raise Errors::NotAuthorized, response.body
       when 404
         raise Errors::NotFound, response.body
       when 503
         raise Errors::RequestToLong, response.body
-      when proc { |code| code != 200 }
-        raise Errors::InvalidResponse, "Response code: #{response.code}"
+      else
+        raise Errors::InvalidResponse, "Response code: #{response.code} message: #{response.body}"
       end
     end
 
+    # default headers for authentication and JSON support
     def headers
       {
-        'Accept' => 'application/json',
+        'Accept'        => 'application/json',
         'Authorization' => "Bearer #{api_key}",
-        'User-Agent' => 'Workable Ruby Client'
+        'Content-Type'  => 'application/json',
+        'User-Agent'    => 'Workable Ruby Client',
       }
     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
+    # @return transformed input if transformation exists for type, raw input otherwise
+    def transform_from(type, input)
+      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
+    end
+
   end
 end

data/lib/workable/version.rb

@@ -1,3 +1,3 @@
 module Workable
-  VERSION = "0.2.0"
+  VERSION = "1.0.0.rc1"
 end

data/lib/workable.rb

@@ -7,7 +7,6 @@ require 'ostruct'
 require_relative "workable/version"
 require_relative "workable/errors"
 require_relative "workable/client"
-require_relative "workable/job"
 
 module Workable
   API_VERSION = "2".freeze

data/spec/lib/workable/client_spec.rb

@@ -47,7 +47,7 @@ describe Workable::Client do
       stub_request(:get, "https://www.workable.com/spi/v2/accounts/subdomain/jobs/03FF356C8B")
         .to_return(status: 200, body: job_json_fixture, headers: {})
 
-      expect(client.job_details('03FF356C8B')).to be_kind_of(Workable::Job)
+      expect(client.job_details('03FF356C8B')).to be_kind_of(Hash)
     end
 
     it 'raises an exception when job is not found' do
@@ -100,4 +100,66 @@ describe Workable::Client do
     end
   end
 
+  describe "#transform_to" do
+    let(:client){
+      described_class.new(
+        api_key: 'test',
+        subdomain: 'subdomain',
+        transform_to: {
+          candidate: OpenStruct.method(:new)
+        }
+      )
+    }
+
+    it "transforms candidate" do
+      result = client.send(:transform_to, :candidate, {:name => "Tom"})
+      expect(result).to be_kind_of(OpenStruct)
+      expect(result.name).to eq("Tom")
+    end
+  end
+
+  describe "#transform_from" do
+    let(:client){
+      described_class.new(
+        api_key: 'test',
+        subdomain: 'subdomain',
+        transform_from: {
+          candidate: lambda { |input| input.marshal_dump }
+        }
+      )
+    }
+
+    it "transforms candidate" do
+      input = client.send(:transform_from, :candidate, OpenStruct.new({:name => "Tom"}))
+      expect(input).to be_kind_of(Hash)
+      expect(input[:name]).to eq("Tom")
+    end
+  end
+
+  describe "#transform" do
+    let(:client){ described_class.new(api_key: 'test', subdomain: 'subdomain') }
+
+    it "transforms one" do
+      result = client.send(:transform, OpenStruct.method(:new), {:name => "Tom"})
+      expect(result).to be_kind_of(OpenStruct)
+      expect(result.name).to eq("Tom")
+    end
+
+    it "transforms many" do
+      data = client.send(:transform, OpenStruct.method(:new), [{:name => "Tom"}, {:name => "Alice"}])
+      expect(data).to be_kind_of(Array)
+      expect(data.map(&:class)).to eq([OpenStruct, OpenStruct])
+    end
+
+    it "does not transform nil" do
+      data = client.send(:transform, OpenStruct.method(:new), nil)
+      expect(data).to eq(nil)
+    end
+
+    it "does not transform without transformation" do
+      data = client.send(:transform, nil, OpenStruct.new({:slug => "sourced"}))
+      expect(data).to eq(OpenStruct.new({:slug => "sourced"}))
+    end
+  end
+
 end

data/workable.gemspec

@@ -6,8 +6,8 @@ require 'workable/version'
 Gem::Specification.new do |spec|
   spec.name          = "workable"
   spec.version       = Workable::VERSION
-  spec.authors       = ["Rafał Wojsznis"]
-  spec.email         = ["rafal.wojsznis@gmail.com"]
+  spec.authors       = ["Rafał Wojsznis", "Michal Papis"]
+  spec.email         = ["rafal.wojsznis@gmail.com", "mpapis@gmail.com"]
   spec.homepage      = "https://github.com/emq/workable"
   spec.license       = "MIT"
   spec.summary = spec.description = "Dead-simple Ruby API client for workable.com"
@@ -19,9 +19,10 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 1.9.3'
 
-  spec.add_development_dependency 'bundler', '~> 1.7'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.1.0'
   spec.add_development_dependency 'webmock', '~> 1.20.4'
   spec.add_development_dependency 'coveralls', '~> 0.7.2'
+  spec.add_development_dependency 'guard', '~> 2.12'
+  spec.add_development_dependency 'guard-rspec', '~> 4.5'
 end

metadata

@@ -1,29 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: workable
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0.rc1
 platform: ruby
 authors:
 - Rafał Wojsznis
+- Michal Papis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-17 00:00:00.000000000 Z
+date: 2015-04-16 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.7'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -80,9 +67,38 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.7.2
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
 description: Dead-simple Ruby API client for workable.com
 email:
 - rafal.wojsznis@gmail.com
+- mpapis@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -92,17 +108,16 @@ files:
 - ".travis.yml"
 - CHANGELOG.md
 - Gemfile
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/workable.rb
 - lib/workable/client.rb
 - lib/workable/errors.rb
-- lib/workable/job.rb
 - lib/workable/version.rb
 - spec/fixtures.rb
 - spec/lib/workable/client_spec.rb
-- spec/lib/workable/job_spec.rb
 - spec/spec_helper.rb
 - workable.gemspec
 homepage: https://github.com/emq/workable
@@ -120,9 +135,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.4.6
@@ -132,5 +147,4 @@ summary: Dead-simple Ruby API client for workable.com
 test_files:
 - spec/fixtures.rb
 - spec/lib/workable/client_spec.rb
-- spec/lib/workable/job_spec.rb
 - spec/spec_helper.rb

data/lib/workable/job.rb

@@ -1,26 +0,0 @@
-module Workable
-  class Job
-    # from main jobs query
-    attr_reader :key, :title, :full_title, :code, :shortcode, :state,
-                :department, :url, :application_url, :shortlink, :location
-
-    # from job details
-    attr_reader :full_description, :description, :requirements, :benefits,
-                :employment_type, :industry, :function, :experience, :education
-
-    def initialize(params)
-      params.each do |key, value|
-        value = OpenStruct.new(value) if value.is_a?(Hash)
-        instance_variable_set("@#{key}", value)
-      end
-    end
-
-    def location_name
-      "#{location.city}, #{location.country}"
-    end
-
-    def created_at
-      Date.parse(@created_at)
-    end
-  end
-end

data/spec/lib/workable/job_spec.rb

@@ -1,10 +0,0 @@
-require 'spec_helper'
-
-describe Workable::Job do
-  it 'parses json response' do
-    job = described_class.new(JSON.parse(job_json_fixture))
-
-    expect(job.location.country_code).to eq 'PL'
-    expect(job.created_at).to be_kind_of(Date)
-  end
-end