bamboozled 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5e8d67307421bf68000afd6ace774f340f25e2dd
-  data.tar.gz: f077d6540b2b8022d3100d420e81aa5de118da63
+  metadata.gz: 635d6d1db5b169bb515d7f4d40a392fcc92e93db
+  data.tar.gz: ddaa342918519a1c1e084b6b887c75996ed3ae2a
 SHA512:
-  metadata.gz: e906a09b6c8dc5c65b37d6e7fba76065f6c89ee3d73d6dc70138d958595c2f17705ffdf14aff9e9e63f78e11f0b890be4b0ca316f06fe6798ea9e52e8a0dd339
-  data.tar.gz: a197f8ebb1f8ddba7a58ae48e0b6bf8caef92e57fc1af05f65629e77879a955532bc69660d28864faa8079467ef9605936917e36e2e91014b282a9f6cdd2c294
+  metadata.gz: c0f19e374b5c96fe7e0a52b3fbef85a26d53858aaa79aec1f76f924ee04e8459b66baa8e93101a327f6afa68ed6645302f5408b34895fee5fcf76fa2919e0996
+  data.tar.gz: 48691b174853d721d92ecf5a7e7d235c0a0f55639e4c42fa3ffbdf8d17003cd9be82b7f3d64884b45e8541788fe8bcc442747d824b7f9fdb07e94918b4348978

data/.gitignore

@@ -10,3 +10,5 @@ doc
 
 # jeweler generated
 pkg
+
+*.gem

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    bamboozled (0.0.1)
+    bamboozled (0.0.2)
       httparty
       json
 

data/Readme.md

@@ -0,0 +1,73 @@
+# Bamboozled
+
+[![Gem Version](https://badge.fury.io/rb/bamboozled.svg)](http://badge.fury.io/rb/bamboozled) [![Code Climate](https://codeclimate.com/github/Skookum/bamboozled.png)](https://codeclimate.com/github/Skookum/bamboozled)
+
+Bamboozled wraps the BambooHR API without the use of Rails dependencies.
+
+# Usage:
+
+```ruby
+# Create the client:
+client = Bamboozled.client('your_subdomain', 'your_api_key')
+```
+
+### Employee related data:
+
+```ruby
+# Returns an array of all employees
+client.employee.all
+
+# Returns a hash of a single employee
+client.employee.find(employee_id, fields = nil)
+
+# Tabular employee data
+client.employee.job_info(employee_id)
+client.employee.employment_status(employee_id)
+client.employee.compensation(employee_id)
+client.employee.dependents(employee_id)
+client.employee.contacts(employee_id)
+
+# Time off estimate for employee. Requires end date in Date or Time format or YY-MM-DD string.
+client.employee.time_off_estimate(employee_id, end_date)
+```
+
+### Time off data
+
+```ruby
+# Get time off requests filtered by a number of parameters
+# :id - the ID of the time off request
+# :action - 
+# :employeeId - the ID of the employee you're looking for
+# :start - filter start date
+# :end - filter end date
+# :type - type of time off request
+# :status - must be one or more of the following: approved denied superceded requested canceled
+client.time_off.requests(:employeeId: employee_id, start: Time.now)
+
+# See who is out when.
+client.time_off.whos_out(Time.now, '2014-12-31')
+```
+
+# Reports
+
+```ruby
+# Find a report by its number
+client.report.find(report_number, format = 'JSON', fd = true)
+```
+
+## Todo:
+
+1. Write tests!
+2. Implement photos endpoints
+3. Implement metadata endpoints
+4. Implement last change information endpoints
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Make some specs pass
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request
+

data/lib/bamboozled/api/base.rb

@@ -0,0 +1,75 @@
+require 'json'
+
+module Bamboozled
+  module API
+    class Base
+      attr_reader :subdomain, :api_key
+
+      def initialize(subdomain, api_key)
+        @subdomain, @api_key = subdomain, api_key
+      end
+
+      protected
+        def request(method, path, options = {})
+          params = {
+            path:    path,
+            options: options,
+            method:  method
+          }
+
+          httparty_options = {
+            query:  options[:query],
+            body:   options[:body],
+            format: :plain,
+            basic_auth: auth,
+            headers: {
+              "Accept"       => "application/json",
+              "User-Agent"   => "Bamboozled/#{Bamboozled::VERSION}"
+            }.update(options[:headers] || {})
+          }
+
+          response = HTTParty.send(method, "#{path_prefix}#{path}", httparty_options)
+          params[:response] = response.inspect.to_s
+
+          case response.code
+          when 200..201
+            begin
+              JSON.load(response, nil)
+            rescue
+              MultiXml.parse(response, symbolize_keys: true)
+            end
+          when 400
+            raise Bamboozled::BadRequest.new(response, params, 'The request was invalid or could not be understood by the server. Resubmitting the request will likely result in the same error.')
+          when 401
+            raise Bamboozled::AuthenticationFailed.new(response, params, 'Your API key is missing.')
+          when 403
+            raise Bamboozled::Forbidden.new(response, params, 'The application is attempting to perform an action it does not have privileges to access. Verify your API key belongs to an enabled user with the required permissions.')
+          when 404
+            raise Bamboozled::NotFound.new(response, params, 'The resource was not found with the given identifier. Either the URL given is not a valid API, or the ID of the object specified in the request is invalid.')
+          when 406
+            raise Bamboozled::NotAcceptable.new(response, params, 'The request contains references to non-existent fields.')
+          when 409
+            raise Bamboozled::Conflict.new(response, params, 'The request attempts to create a duplicate. For employees, duplicate emails are not allowed. For lists, duplicate values are not allowed.')
+          when 429
+            raise Bamboozled::LimitExceeded.new(response, params, 'The account has reached its employee limit. No additional employees could be added.')
+          when 500
+            raise Bamboozled::InternalServerError.new(response, params, 'The server encountered an error while processing your request and failed.')
+          when 502
+            raise Bamboozled::GatewayError.new(response, params, 'The load balancer or web server had trouble connecting to the Bamboo app. Please try the request again.')
+          when 503
+            raise Bamboozled::ServiceUnavailable.new(response, params, 'The service is temporarily unavailable. Please try the request again.')
+          else
+            raise Bamboozled::InformBamboo.new(response, params, 'An error occurred that we do not now how to handle. Please contact BambooHR.')
+          end
+        end
+
+        def auth
+          { username: api_key, password: "x" }
+        end
+
+        def path_prefix
+          "https://api.bamboohr.com/api/gateway.php/#{subdomain}/v1/"
+        end
+    end
+  end
+end

data/lib/bamboozled/api/employee.rb

@@ -0,0 +1,41 @@
+module Bamboozled
+  module API
+    class Employee < Base
+
+      def all(fields = nil)
+        fields = all_fields if fields.nil?
+        fields = fields.join(',') if fields.is_a?(Array)
+
+        response = request(:get, "employees/directory?fields=#{fields}")
+        response['employees']
+      end
+
+      def find(id, fields = nil)
+        fields = all_fields if fields.nil?
+        fields = fields.join(',') if fields.is_a?(Array)
+
+        request(:get, "employees/#{id}?fields=#{fields}")
+      end
+
+      # Tabular data
+      [:job_info, :employment_status, :compensation, :dependents, :contacts].each do |action|
+        define_method(action.to_s) do |argument_id|
+          request(:get, "employees/#{argument_id}/tables/#{action.to_s.gsub(/_(.)/) {|e| $1.upcase}}")
+        end
+      end
+
+      def time_off_estimate(id, end_date)
+        end_date = end_date.strftime("%F") unless end_date.is_a?(String)
+        request(:get, "employees/#{id}/time_off/calculator?end=#{end_date}")
+      end
+
+      def default_fields
+        %w(displayName firstName lastName jobTitle workPhone mobilePhone workEmail department location photoUploaded photoUrl canUploadPhoto).join(',')
+      end
+
+      def all_fields
+        %w(address1 address2 age bestEmail birthday city country dateOfBirth department division eeo employeeNumber employmentHistoryStatus ethnicity exempt firstName flsaCode fullName1 fullName2 fullName3 fullName4 fullName5 displayName gender hireDate homeEmail homePhone id jobTitle lastChanged lastName location maritalStatus middleName mobilePhone nickname payChangeReason payGroup payGroupId payRate payRateEffectiveDate payType ssn sin state stateCode status supervisor supervisorId supervisorEId terminationDate workEmail workPhone workPhonePlusExtension workPhoneExtension zipcode photoUploaded rehireDate standardHoursPerWeek bonusDate bonusAmount bonusReason bonusComment commissionDate commisionDate commissionAmount commissionComment).join(',')
+      end
+    end
+  end
+end

data/lib/bamboozled/api/report.rb

@@ -0,0 +1,15 @@
+module Bamboozled
+  module API
+    class Report < Base
+
+      def find(number, format = 'JSON', fd = true)
+        request(:get, "reports/#{number}?format=#{format.upcase}&fd=#{fd.yesno}")
+      end
+
+      # TODO - Implement custom reports
+      # def custom(options, format = 'JSON')
+      #   request(:post, "reports/custom?format=#{format.upcase}", data_should_go_here)
+      # end
+    end
+  end
+end

data/lib/bamboozled/api/time_off.rb

@@ -0,0 +1,30 @@
+module Bamboozled
+  module API
+    class TimeOff < Base
+
+      def requests(options = {})
+        allowed_parameters = [:id, :action, :employeeId, :start, :end, :type, :status]
+        options = options.keep_if { |k,_| allowed_parameters.include? k }
+
+        # Convert non string dates to strings.
+        [:start, :end].each do |action|
+          options[action] = options[action].strftime("%F") if options[action] && !options[action].is_a?(String)
+        end
+
+        # Make sure all statuses are allowed
+        if options[:status]
+          allowed_statuses = %w(approved denied superceded requested canceled)
+          options[:status] = Array(options[:status]).keep_if { |v| allowed_statuses.include? v }.join(",")
+        end
+
+        request(:get, "time_off/requests?#{URI.encode_www_form(options)}")
+      end
+
+      def whos_out(start_date, end_date = nil)
+        start_date = start_date.strftime("%F") unless start_date.is_a?(String)
+        end_date = end_date.strftime("%F") unless end_date.nil? || end_date.is_a?(String)
+        request(:get, "time_off/whos_out?start=#{start_date}&end=#{end_date}")
+      end
+    end
+  end
+end

data/lib/bamboozled/base.rb

@@ -0,0 +1,21 @@
+module Bamboozled
+  class Base
+    attr_reader :request
+
+    def initialize(subdomain: nil, api_key: nil)
+      @subdomain, @api_key = subdomain, api_key
+    end
+
+    def employee
+      @employee ||= Bamboozled::API::Employee.new(@subdomain, @api_key)
+    end
+
+    def report
+      @report ||= Bamboozled::API::Report.new(@subdomain, @api_key)
+    end
+
+    def time_off
+      @time_off ||= Bamboozled::API::TimeOff.new(@subdomain, @api_key)
+    end
+  end
+end

data/lib/bamboozled/errors.rb

@@ -0,0 +1,31 @@
+module Bamboozled
+  class HTTPError < StandardError
+    attr_reader :response
+    attr_reader :params
+    attr_reader :hint
+
+    def initialize(response, params = {}, hint = nil)
+      @response = response
+      @params = params
+      @hint = hint
+      super(response)
+    end
+
+    def to_s
+      "#{self.class.to_s} : #{response.code} #{response.body}" + (hint ? "\n#{hint}" : "")
+    end
+  end
+
+  # 400
+  class BadRequest < HTTPError; end #400
+  class Unauthorized < HTTPError ; end #
+  class Forbidden < HTTPError ; end # 403
+  class NotFound < HTTPError; end # 404
+  class NotAcceptable < HTTPError; end # 406
+  class Conflict < HTTPError; end # 409
+  class LimitExceeded < HTTPError; end # 429
+  class InternalServerError < HTTPError; end # 500
+  class GatewayError < HTTPError; end # 502
+  class ServiceUnavailable < HTTPError; end # 503
+  class InformBamboo < HTTPError; end
+end

data/lib/bamboozled/version.rb

@@ -1,3 +1,3 @@
 module Bamboozled
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/bamboozled.rb

@@ -2,9 +2,19 @@ require 'httparty'
 require 'json'
 require 'uri'
 
-Dir[File.dirname(__FILE__) + '/bamboozled/*.rb'].each do |file|
-  require file
-end
+require 'bamboozled/ext/yesno'
+
+require 'bamboozled/version'
+require 'bamboozled/errors'
+require 'bamboozled/base'
+
+%w(base employee report time_off).each {|a| require "bamboozled/api/#{a}"}
 
 module Bamboozled
+  class << self
+    # Creates a standard client that will raise all errors it encounters
+    def client(subdomain: nil, api_key: nil)
+      Bamboozled::Base.new(subdomain: subdomain, api_key: api_key)
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bamboozled
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Mark Rickert
@@ -48,11 +48,17 @@ files:
 - ".gitignore"
 - Gemfile
 - Gemfile.lock
+- Readme.md
 - bamboozled.gemspec
 - lib/bamboozled.rb
-- lib/bamboozled/client.rb
+- lib/bamboozled/api/base.rb
+- lib/bamboozled/api/employee.rb
+- lib/bamboozled/api/report.rb
+- lib/bamboozled/api/time_off.rb
+- lib/bamboozled/base.rb
+- lib/bamboozled/errors.rb
+- lib/bamboozled/ext/yesno.rb
 - lib/bamboozled/version.rb
-- lib/bamboozled/yesno.rb
 homepage: http://github.com/Skookum/bamboozled
 licenses:
 - MIT

data/lib/bamboozled/client.rb

@@ -1,132 +0,0 @@
-module Bamboozled
-  class Client
-    include HTTParty
-    base_uri 'api.bamboohr.com'
-
-    def initialize(subdomain, api_key)
-      @subdomain, @api_key = subdomain, api_key
-    end
-
-    def all_employees(fields = nil)
-      fields = all_fields if fields.nil?
-      r = request("employees/directory?fields=#{fields}")
-      r['employees']
-    end
-
-    def employee(id, fields = nil)
-      fields = all_fields if fields.nil?
-      request("employees/#{id}?fields=#{fields}")
-    end
-
-    # Tabular data
-    [:job_info, :employment_status, :compensation, :dependents, :contacts].each do |action|
-      define_method("employee_#{action}") do |argument_id|
-        request("employees/#{argument_id}/tables/#{action.to_s.gsub(/_(.)/) {|e| $1.upcase}}")
-      end
-    end
-
-    # Reports
-    def report(number, format = 'JSON', fd = true)
-      request("reports/#{number}?format=#{format.upcase}&fd=#{fd.yesno}")
-    end
-
-    # def custom_report(options, format = 'JSON')
-    #   post("reports/custom?format=#{format.upcase}", nil)
-    # end
-
-    # Time Off Requests
-    def time_off_requests(options = {})
-      allowed_parameters = [:id, :action, :employeeId, :start, :end, :type, :status]
-      options = options.keep_if { |k,_| allowed_parameters.include? k }
-
-      # Convert non string dates to strings.
-      [:start, :end].each do |action|
-        options[action] = options[action].strftime("%F") if options[action] && !options[action].is_a?(String)
-      end
-
-      # Make sure all statuses are allowed
-      if options[:status]
-        allowed_statuses = %w(approved denied superceded requested canceled)
-        options[:status] = Array(options[:status]).keep_if { |v| allowed_statuses.include? v }.join(",")
-      end
-
-      request("time_off/requests?#{URI.encode_www_form(options)}")
-    end
-
-    def estimate_time_off(employee_id, end_date)
-      end_date = end_date.strftime("%F") unless end_date.is_a?(String)
-      request("employees/#{employee_id}/time_off/calculator?end=#{end_date}")
-    end
-
-    def whos_out(start_date, end_date = nil)
-      start_date = start_date.strftime("%F") unless start_date.is_a?(String)
-      end_date = end_date.strftime("%F") unless end_date.nil? || end_date.is_a?(String)
-      request("time_off/whos_out?start=#{start_date}&end=#{end_date}")
-    end
-
-    def default_fields
-      %w(displayName firstName lastName jobTitle workPhone mobilePhone workEmail department location photoUploaded photoUrl canUploadPhoto).join(',')
-    end
-
-    def all_fields
-      %w(address1 address2 age bestEmail birthday city country dateOfBirth department division eeo employeeNumber employmentHistoryStatus ethnicity exempt firstName flsaCode fullName1 fullName2 fullName3 fullName4 fullName5 displayName gender hireDate homeEmail homePhone id jobTitle lastChanged lastName location maritalStatus middleName mobilePhone nickname payChangeReason payGroup payGroupId payRate payRateEffectiveDate payType ssn sin state stateCode status supervisor supervisorId supervisorEId terminationDate workEmail workPhone workPhonePlusExtension workPhoneExtension zipcode photoUploaded rehireDate standardHoursPerWeek bonusDate bonusAmount bonusReason bonusComment commissionDate commisionDate commissionAmount commissionComment).join(',')
-    end
-
-    private
-
-    def request(path, fields = nil)
-      fields = all_fields if fields.nil?
-      self.class.get("#{path_prefix}#{path}", basic_auth: auth, headers: headers)
-    end
-
-    def post(path, data)
-      self.class.post("#{path_prefix}#{path}", body: data, basic_auth: auth, headers: headers)
-    end
-
-    def headers
-      { 'Accept' => 'application/json' }
-    end
-
-    def auth
-      { username: @api_key, password: "x" }
-    end
-
-    def path_prefix
-      "/api/gateway.php/#{@subdomain}/v1/"
-    end
-
-    # def self.get_all_stores
-    #   get("/v1/stores")
-    # end
-
-    # def self.get_stores_by_zip(zip)
-    #   get("/v1/stores(postalCode=#{zip})")
-    # end
-
-    # def self.get_stores_by_zip_and_distance(zip, distance)
-    #   get("/v1/stores(area(#{zip},#{distance}))")
-    # end
-
-    # def self.get_product_by_sku(sku)
-    #   get("/v1/products/#{sku}.xml")
-    # end
-
-    # def self.get_products(filter)
-    #   response = get(URI.escape("/v1/products(#{filter})"))
-    #   response["products"]["product"]
-    # end
-
-    # def self.method_missing(method_id, *args)
-    #   if match = /get_products_by_([_a-zA-Z]\w*)/.match(method_id.to_s)
-    #     attribute_names = match.captures.last.split('_and_')
-
-    #     request = ""
-    #     attribute_names.each_with_index { |name, idx| request = request + name + "=" + args[idx] + (attribute_names.length-1 == idx ? "" : "&") }
-
-    #     get_products(request)
-    #   else
-    #     super
-    #   end
-    # end
-  end
-end