people_doc 0.1.0

data/README.md

@@ -0,0 +1,81 @@
+[![CircleCI](https://circleci.com/gh/westernmilling/people_doc.svg?style=svg&circle-token=f5b3c58d525d1d975f632b779221c1588cfeba97)](https://circleci.com/gh/westernmilling/people_doc)
+[![Maintainability](https://api.codeclimate.com/v1/badges/6ade98502a90fe627e29/maintainability)](https://codeclimate.com/github/westernmilling/people_doc/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/6ade98502a90fe627e29/test_coverage)](https://codeclimate.com/github/westernmilling/people_doc/test_coverage)
+
+# PeopleDoc
+Basic Ruby client library for the PeopleDoc REST APIs
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'people_doc'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install people_doc
+
+## Usage
+
+### RESTv1
+
+```ruby
+client = PeopleDoc::V1::Client.new(
+  api_key: 'api_key'
+  base_url: 'https://api.staging.us.people-doc.com'
+  logger: Logger.new(STDOUT)
+)
+
+response = client.get('employees/12345678')
+```
+
+### RESTv2
+
+```ruby
+client = PeopleDoc::V2::Client.new(
+  config.application_id = 'application_id'
+  config.application_secret = 'application_secret'
+  config.base_url = 'https://apis.staging.us.people-doc.com'
+  config.client_id = 'client_id'
+  config.logger = Logger.new(STDOUT)
+)
+
+response = client.get('organizations/ABC')
+```
+
+## Supported Functionality
+
+- RESTv1
+  - GET
+  - POST
+  - POST with file
+
+- RESTv2
+  - GET
+  - POST
+  - PUT
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/westernmilling/people_doc. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the PeopleDoc client project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/westernmilling/people_doc/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %w(spec rubocop)

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "adp_client"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/lib/people_doc/httparty_request.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'httparty'
+require 'people_doc/response_handlers'
+
+module PeopleDoc
+  class HTTPartyRequest
+    def initialize(base_url, logger, response_handlers = [])
+      @base_url = base_url
+      @logger = logger
+      @response_handlers = response_handlers
+    end
+
+    def get(headers, resource)
+      url = "#{@base_url}/#{resource}"
+
+      @logger.debug("GET request Url: #{url}")
+      @logger.debug("-- Headers: #{headers}")
+
+      raises_unless_success do
+        HTTParty
+          .get(url, headers: headers)
+      end.parsed_response
+    end
+
+    def perform_request(headers, resource, payload)
+      http_method = __callee__
+      url = "#{@base_url}/#{resource}"
+
+      @logger.debug("#{http_method.upcase} request Url: #{url}")
+      @logger.debug("-- Headers: #{headers}")
+      @logger.debug("-- Payload: #{payload}")
+
+      raises_unless_success do
+        HTTParty
+          .send(http_method.to_sym, url, body: payload, headers: headers)
+      end.parsed_response
+    end
+    alias_method :put, :perform_request
+    alias_method :post, :perform_request
+
+    def post_file(headers, resource, payload)
+      http_method = 'post'
+      url = "#{@base_url}/#{resource}"
+
+      @logger.debug("#{http_method.upcase} request Url: #{url} (POST file)")
+      @logger.debug("-- Headers: #{headers}")
+      @logger.debug("-- Payload: #{payload}")
+
+      raises_unless_success do
+        HTTMultiParty
+          .send(http_method.to_sym, url, body: payload, headers: headers)
+      end.parsed_response
+    end
+
+    protected
+
+    def raises_unless_success
+      httparty = yield
+
+      @response_handlers.each_value do |handler_type|
+        handler_type.new(httparty).call
+      end
+
+      httparty
+    end
+  end
+end

data/lib/people_doc/response_handlers.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+module PeopleDoc
+  module ResponseHandlers
+    class BaseHandler
+      def initialize(httparty)
+        @httparty = httparty
+      end
+    end
+
+    class HandleBadRequest < BaseHandler
+      def call
+        fail BadRequest.new(@httparty.body, @httparty.parsed_response) \
+          if @httparty.code == 400
+      end
+    end
+
+    class HandleNotFound < BaseHandler
+      def call
+        fail NotFound.new(@httparty.body) if @httparty.code == 404
+      end
+    end
+
+    class HandleUnauthorized < BaseHandler
+      def call
+        fail Unauthorized.new(@httparty.body) \
+          if [401, 403].include?(@httparty.code)
+      end
+    end
+
+    class HandleUnprocessableEntity < BaseHandler
+      def call
+        return unless @httparty.code == 422
+
+        message = format(
+          '%<code>s: %<message>s',
+          code: @httparty.parsed_response['code'],
+          message: @httparty.parsed_response['message']
+        )
+        message += "\r\n\r\n"
+        message += @httparty
+                   .parsed_response['errors']
+                   .map { |error| "#{error['field']} - #{error['message']}" }
+                   .join("\r\n")
+
+        fail UnprocessableEntity.new(message, @httparty.parsed_response)
+      end
+    end
+
+    class HandleUnknownFailure < BaseHandler
+      def call
+        fail HTTParty::Error.new(
+          "Code #{@httparty.code} - #{@httparty.body}"
+        ) unless @httparty.response.is_a?(Net::HTTPSuccess)
+      end
+    end
+
+    module V1
+      class HandleBadRequest < PeopleDoc::ResponseHandlers::BaseHandler
+        def call
+          return unless @httparty.code == 400
+
+          message = if @httparty.parsed_response['errors']
+                      ErrorsResponse.new(@httparty).call
+                    elsif @httparty.parsed_response['message']
+                      MessageResponse.new(@httparty).call
+                    else
+                      @httparty.body
+                    end
+
+          fail BadRequest.new(message, @httparty.parsed_response)
+        end
+
+        class ErrorsResponse
+          def initialize(response)
+            @response = response
+          end
+
+          def call
+            @response
+              .parsed_response['errors']
+              .map { |error| error['msg'] }
+              .join("\r\n")
+          end
+        end
+
+        class MessageResponse
+          def initialize(response)
+            @response = response
+          end
+
+          def call
+            @response.parsed_response['message']
+          end
+        end
+      end
+    end
+
+    module V2
+      class HandleBadRequest < PeopleDoc::ResponseHandlers::BaseHandler
+        def call
+          return unless @httparty.code == 400
+
+          message = @httparty.parsed_response['error_description']
+
+          fail BadRequest.new(message, @httparty.parsed_response)
+        end
+      end
+
+      class HandleUnauthorized < BaseHandler
+        def call
+          return unless @httparty.code == 401
+
+          message = if @httparty.parsed_response['error']
+                      format(
+                        '%<error>s: %<description>s',
+                        error: @httparty.parsed_response['error'],
+                        description: @httparty
+                                     .parsed_response['error_description']
+                      )
+                    elsif @httparty.parsed_response['code']
+                      format(
+                        '%<code>s: %<message>s',
+                        code: @httparty.parsed_response['code'],
+                        message: @httparty.parsed_response['message']
+                      )
+                    else
+                      @httparty.body
+                    end
+
+          fail Unauthorized.new(message)
+        end
+      end
+    end
+  end
+end

data/lib/people_doc/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PeopleDoc
+  VERSION = '0.1.0'
+end

data/lib/people_doc.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+# $LOAD_PATH.unshift File.dirname(__FILE__)
+
+require 'people_doc/version'
+require 'people_doc/httparty_request'
+require 'logger'
+
+module PeopleDoc
+  RESPONSE_HANDLERS = {
+    bad_request: ResponseHandlers::HandleBadRequest,
+    not_found: ResponseHandlers::HandleNotFound,
+    unauthorized: ResponseHandlers::HandleUnauthorized,
+    unprocessable_entity: ResponseHandlers::HandleUnprocessableEntity,
+    unknown: ResponseHandlers::HandleUnknownFailure
+  }.freeze
+
+  class BaseError < StandardError
+    attr_reader :response
+
+    def initialize(message = nil, response = nil)
+      super(message)
+
+      @response = response
+    end
+  end
+  class BadRequest < BaseError; end
+  class NotFound < BaseError; end
+  class Unauthorized < BaseError; end
+  class UnprocessableEntity < BadRequest; end
+  class Token
+    attr_accessor :access_token, :token_type, :expires_in
+
+    def initialize(access_token, token_type, expires_in)
+      @access_token = access_token
+      @token_type = token_type
+      @expires_in = expires_in
+    end
+  end
+
+  module V1
+    class << self
+      attr_accessor :api_key,
+                    :base_url,
+                    :logger
+
+      ##
+      # Configures default PeopleDoc REST APIv1 settings.
+      #
+      # @example configuring the client defaults
+      #   PeopleDoc::V1.configure do |config|
+      #     config.api_key = 'api_key'
+      #     config.base_url = 'https://api.staging.us.people-doc.com'
+      #     config.logger = Logger.new(STDOUT)
+      #   end
+      #
+      # @example using the client
+      #   client = PeopleDoc::V1::Client.new
+      def configure
+        yield self
+        true
+      end
+    end
+
+    ##
+    # PeopleDoc REST API v1 Client
+    class Client
+      def initialize(options = {})
+        options = default_options.merge(options)
+
+        @api_key = options.fetch(:api_key)
+        @base_url = options.fetch(:base_url)
+        @logger = options.fetch(:logger, Logger.new(STDOUT))
+        @request = HTTPartyRequest.new(@base_url, @logger, response_handlers)
+      end
+
+      ##
+      # Get a resource
+      # Makes a request for a resource from PeopleDoc and returns the response
+      # as a raw {Hash}.
+      #
+      # @param [String] the resource endpoint
+      # @return [Hash] response data
+      def get(resource)
+        @request
+          .get(base_headers, "api/v1/#{resource}")
+      rescue NotFound
+        nil
+      end
+
+      ##
+      # POST a resource
+      # Makes a request to post new or existing resource details to PeopleDoc.
+      #
+      # @param [String] the resource endpoint
+      # @param [Hash] payload data
+      # @return [Hash] response data
+      def post(resource, payload)
+        @request.post(
+          base_headers,
+          "api/v1/#{resource}/",
+          payload.to_json
+        )
+      end
+
+      ##
+      # POST a file
+      # ...
+      #
+      # @param [String] the resource endpoint
+      # @param [...] file
+      # @param [Hash] payload data
+      # @return [Hash] response data
+      def post_file(resource, file, payload)
+        @request.post_file(
+          base_headers.merge(
+            'Content-Type' => 'multipart/form-data'
+          ),
+          "api/v1/#{resource}/",
+          file: file,
+          data: payload.to_json
+        )
+      end
+
+      protected
+
+      def base_headers
+        {
+          'Accept' => 'application/json',
+          'X-API-KEY' => @api_key,
+          'Content-Type' => 'application/json',
+          'Host' => uri.host,
+          'User-Agent' => 'PeopleDoc::V1::Client'
+        }
+      end
+
+      ##
+      # Default options
+      # A {Hash} of default options populate by attributes set during
+      # configuration.
+      #
+      # @return [Hash] containing the default options
+      def default_options
+        {
+          api_key: PeopleDoc::V1.api_key,
+          base_url: PeopleDoc::V1.base_url,
+          logger: PeopleDoc::V1.logger
+        }
+      end
+
+      def response_handlers
+        RESPONSE_HANDLERS.merge(
+          bad_request: PeopleDoc::ResponseHandlers::V1::HandleBadRequest
+        )
+      end
+
+      def uri
+        @uri ||= URI.parse(@base_url)
+      end
+    end
+  end
+
+  module V2
+    class << self
+      attr_accessor :application_id,
+                    :application_secret,
+                    :base_url,
+                    :client_id,
+                    :logger
+
+      ##
+      # Configures default PeopleDoc REST APIv1 settings.
+      #
+      # @example configuring the client defaults
+      #   PeopleDoc::V2.configure do |config|
+      #     config.application_id = 'application_id'
+      #     config.application_secret = 'application_secret'
+      #     config.base_url = 'https://apis.staging.us.people-doc.com'
+      #     config.client_id = 'client_id'
+      #     config.logger = Logger.new(STDOUT)
+      #   end
+      #
+      # @example using the client
+      #   client = PeopleDoc::V2::Client.new
+      def configure
+        yield self
+        true
+      end
+    end
+
+    ##
+    # PeopleDoc REST API v2 Client
+    class Client
+      def initialize(options = {})
+        options = default_options.merge(options)
+
+        @application_id = options.fetch(:application_id)
+        @application_secret = options.fetch(:application_secret)
+        @base_url = options.fetch(:base_url)
+        @client_id = options.fetch(:client_id)
+        @logger = options.fetch(:logger, Logger.new(STDOUT))
+        @request = HTTPartyRequest.new(@base_url, @logger, response_handlers)
+      end
+
+      def encoded_credentials
+        EncodedCredentials.new(@application_id, @application_secret).call
+      end
+
+      ##
+      # OAuth token
+      # Performs authentication using client credentials against the
+      # PeopleDoc Api.
+      #
+      # @return [Token] token details
+      def token
+        return @token if @token
+
+        payload = {
+          client_id: @client_id,
+          grant_type: 'client_credentials',
+          scope: 'client'
+        }
+        headers = {
+          'Accept' => 'application/json',
+          'Authorization' => "Basic #{encoded_credentials}",
+          'Content-Type' => 'application/x-www-form-urlencoded',
+          'Host' => uri.host,
+          'User-Agent' => 'PeopleDoc::V2::Client'
+        }
+
+        response = @request.post(headers, 'api/v2/client/tokens', payload)
+
+        @token = Token.new(
+          *response.values_at('access_token', 'token_type', 'expires_in')
+        )
+      end
+
+      ##
+      # Get a resource
+      # Makes a request for a resource from PeopleDoc and returns the response
+      # as a raw {Hash}.
+      #
+      # @param [String] the resource endpoint
+      # @return [Hash] response data
+      def get(resource)
+        @request
+          .get(base_headers, "api/v2/client/#{resource}")
+      rescue NotFound
+        nil
+      end
+
+      ##
+      # POST a file
+      # ...
+      #
+      # @param [String] the resource endpoint
+      # @param [...] file
+      # @param [Hash] payload data
+      # @return [Hash] response data
+      def post_file(resource, file, payload = nil)
+        @request.post_file(
+          base_headers.merge(
+            'Content-Type' => 'multipart/form-data'
+          ),
+          "api/v2/#{resource}",
+          file: file,
+          data: payload ? payload.to_json : nil
+        )
+      end
+
+      ##
+      # PUT a resource
+      # Makes a request to PUT new or existing resource details to PeopleDoc.
+      #
+      # @param [String] the resource endpoint
+      # @param [Hash] payload data
+      # @return [Hash] response data
+      def put(resource, payload)
+        @request.put(
+          base_headers,
+          "api/v2/client/#{resource}",
+          payload.to_json
+        )
+      end
+
+      protected
+
+      def base_headers
+        {
+          'Accept' => 'application/json',
+          'Authorization' => "Bearer #{token.access_token}",
+          'Content-Type' => 'application/json',
+          'Host' => uri.host,
+          'User-Agent' => 'PeopleDoc::V2::Client'
+        }
+      end
+
+      ##
+      # Default options
+      # A {Hash} of default options populate by attributes set during
+      # configuration.
+      #
+      # @return [Hash] containing the default options
+      def default_options
+        {
+          application_id: PeopleDoc::V2.application_id,
+          application_secret: PeopleDoc::V2.application_secret,
+          base_url: PeopleDoc::V2.base_url,
+          client_id: PeopleDoc::V2.client_id,
+          logger: PeopleDoc::V2.logger
+        }
+      end
+
+      def response_handlers
+        RESPONSE_HANDLERS.merge(
+          bad_request: PeopleDoc::ResponseHandlers::V2::HandleBadRequest,
+          unauthorized: PeopleDoc::ResponseHandlers::V2::HandleUnauthorized
+        )
+      end
+
+      def uri
+        @uri ||= URI.parse(@base_url)
+      end
+    end
+
+    class EncodedCredentials
+      def initialize(application_id, application_secret)
+        @application_id = application_id
+        @application_secret = application_secret
+      end
+
+      def call
+        Base64.strict_encode64("#{@application_id}:#{@application_secret}")
+      end
+    end
+  end
+end

data/people_doc.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'people_doc/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'people_doc'
+  spec.version = PeopleDoc::VERSION
+  spec.authors = ['Joseph Bridgwater-Rowe']
+  spec.email = ['joe@westernmilling.com']
+  spec.summary = 'Basic PeopleDoc REST API client'
+  spec.homepage = 'https://github.com/westernmilling/people_doc'
+  spec.license = 'MIT'
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+  spec.add_runtime_dependency 'httparty'
+  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'factory_bot'
+  spec.add_development_dependency 'faker'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rspec_junit_formatter'
+  spec.add_development_dependency 'rubocop', '0.54.0'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'webmock'
+end