procore 0.6.7

data/lib/procore/defaults.rb

@@ -0,0 +1,19 @@
+require "procore/version"
+
+module Procore
+  # Specifies some sensible defaults for certain configurations + clients
+  class Defaults
+    # Default API endpoint
+    API_ENDPOINT = "https://app.procore.com".freeze
+
+    # Default User Agent header string
+    USER_AGENT = "Procore Ruby Gem #{Procore::VERSION}".freeze
+
+    def self.client_options
+      {
+        host: Procore.configuration.host,
+        user_agent: Procore.configuration.user_agent,
+      }
+    end
+  end
+end

data/lib/procore/errors.rb

@@ -0,0 +1,63 @@
+module Procore
+  # Generic / catch all error class. All other errors generated by the gem
+  # inherit from this class.
+  class Error < StandardError
+    # Human readable error message.
+    attr_reader :message
+
+    # A Response object which contains details about the request.
+    attr_reader :response
+
+    def initialize(message, response: nil)
+      @message = message
+      @response = response
+
+      super(message)
+    end
+  end
+
+  # Raised when the gem cannot connect to the Procore API. Possible causes:
+  # Procore is down or the network is doing something funny.
+  APIConnectionError = Class.new(Error)
+
+  # Raised when the request is attempting to access a resource the token's
+  # owner does not have access to.
+  AuthorizationError = Class.new(Error)
+
+  # Raised when the request is incorrectly formated. Possible causes: missing
+  # required parameters or sending a request to access a non-existent resource.
+  InvalidRequestError = Class.new(Error)
+
+  # Raised when the request 404's
+  NotFoundError = Class.new(Error)
+
+  # Raised whenever there is a problem with OAuth. Possible causes: required
+  # credentials are missing or an access token failed to refresh.
+  class OAuthError < Error
+    def initialize(message, response: nil)
+      @message = message
+
+      duck_response = if response
+                        OpenStruct.new(
+                          code: response.status,
+                          body: response.parsed.presence || response.body,
+                          headers: response.headers,
+                          request: OpenStruct.new(
+                            options: {},
+                            path: nil
+                          ),
+                        )
+                      end
+
+      super(message, response: duck_response)
+    end
+  end
+
+  # Raised when a token reaches it's request limit for the current time period.
+  # If you are receiving this error then you are making too many requests
+  # against the Procore API.
+  RateLimitError = Class.new(Error)
+
+  # Raised when a Procore endpoint returns a 500x resonse code.
+  ServerError = Class.new(Error)
+end

data/lib/procore/requestable.rb

@@ -0,0 +1,217 @@
+require "httparty"
+
+module Procore
+  # Module which defines HTTP verbs GET, POST, PATCH and DELETE. Is included in
+  # Client. Has support for Idempotency Tokens on POST and PATCH.
+  #
+  # @example Using #get:
+  #   client.get("my_open_items", per_page: 5)
+  #
+  # @example Using #post:
+  #   client.post("projects", name: "New Project")
+  module Requestable
+    # @param path [String] URL path
+    # @param query [Hash] Query options to pass along with the request
+    #
+    # @example Usage
+    #   client.get("my_open_items", per_page: 5, filter: {})
+    #
+    # @return [Response]
+    def get(path, query = {})
+      Util.log_info(
+        "API Request Initiated",
+        path: "#{base_api_path}/#{path}",
+        method: "GET",
+        query: "#{query}",
+      )
+
+      with_response_handling do
+        HTTParty.get(
+          "#{base_api_path}/#{path}",
+          query: query,
+          headers: headers,
+          timeout: Procore.configuration.timeout,
+        )
+      end
+    end
+
+    # @param path [String] URL path
+    # @param body [Hash] Body parameters to send with the request
+    # @param options [Hash} Extra request options
+    # TODO Add description for idempotency key
+    # @option options [String] :idempotency_token
+    #
+    # @example Usage
+    #   client.post("users", { name: "New User" }, { idempotency_token: "key" })
+    #
+    # @return [Response]
+    def post(path, body = {}, options = {})
+      Util.log_info(
+        "API Request Initiated",
+        path: "#{base_api_path}/#{path}",
+        method: "POST",
+        body: "#{body}",
+      )
+
+      with_response_handling do
+        HTTParty.post(
+          "#{base_api_path}/#{path}",
+          body: body.to_json,
+          headers: headers(options),
+          timeout: Procore.configuration.timeout,
+        )
+      end
+    end
+
+    # @param path [String] URL path
+    # @param body [Hash] Body parameters to send with the request
+    # @param options [Hash} Extra request options
+    # TODO Add description for idempotency token
+    # @option options [String] :idempotency_token
+    #
+    #   client.patch("users/1", { name: "Updated" }, { idempotency_token: "key" })
+    #
+    # @return [Response]
+    def patch(path, body = {}, options = {})
+      Util.log_info(
+        "API Request Initiated",
+        path: "#{base_api_path}/#{path}",
+        method: "PATCH",
+        body: "#{body}",
+      )
+
+      with_response_handling do
+        HTTParty.patch(
+          "#{base_api_path}/#{path}",
+          body: body.to_json,
+          headers: headers(options),
+          timeout: Procore.configuration.timeout,
+        )
+      end
+    end
+
+    # @param path [String] URL path
+    # @param query [Hash] Query options to pass along with the request
+    #
+    # @example Usage
+    #   client.delete("users/1")
+    #
+    # @return [Response]
+    def delete(path, query = {}, options = {})
+      Util.log_info(
+        "API Request Initiated",
+        path: "#{base_api_path}/#{path}",
+        method: "DELETE",
+        query: "#{query}",
+      )
+
+      with_response_handling do
+        HTTParty.delete(
+          "#{base_api_path}/#{path}",
+          query: query,
+          headers: headers,
+          timeout: Procore.configuration.timeout,
+        )
+      end
+    end
+
+    private
+
+    def with_response_handling
+      request_start_time = Time.now
+      retries = 0
+
+      begin
+        result = yield
+      rescue Timeout::Error, Errno::ECONNREFUSED => e
+        if retries <= Procore.configuration.max_retries
+          retries += 1
+          sleep 1.5 ** retries
+          retry
+        else
+          raise APIConnectionError.new(
+            "Cannot connect to the Procore API. Double check your timeout "    \
+            "settings to ensure requests are not being cancelled before they " \
+            "can complete. Try setting the timeout and max_retries to larger " \
+            "values."
+          ), e
+        end
+      end
+
+      response = Procore::Response.new(
+        body: result.body,
+        headers: result.headers,
+        code: result.code,
+        request: result.request,
+      )
+
+      case result.code
+      when 200..299
+        Util.log_info(
+          "API Request Finished ",
+          path: result.request.path,
+          status: "#{result.code}",
+          duration: "#{((Time.now - request_start_time) * 1000).round(0)}ms",
+          request_id: result.headers["x-request-id"],
+        )
+      else
+        Util.log_error(
+          "API Request Failed",
+          path: result.request.path,
+          status: "#{result.code}",
+          duration: "#{((Time.now - request_start_time) * 1000).round(0)}ms",
+          request_id: result.headers["x-request-id"],
+          retries: retries
+        )
+      end
+
+      case result.code
+      when 200..299
+        response
+      when 401
+        raise Procore::AuthorizationError.new(
+          "The request failed because you lack the correct credentials to "    \
+          "access the target resource",
+          response: response,
+        )
+      when 404
+        raise Procore::NotFoundError.new(
+          "The URI requested is invalid or the resource requested does not "   \
+          "exist.",
+          response: response,
+        )
+      when 422
+        raise Procore::InvalidRequestError.new(
+          "Bad Request.",
+          response: response,
+        )
+      when 429
+        raise Procore::RateLimitError.new(
+          "You have surpassed the max number of requests for an hour. Please " \
+          "wait until your limit resets.",
+          response: response,
+        )
+      else
+        raise Procore::ServerError.new(
+          "Something is broken. This is usually a temporary error - Procore "  \
+          "may be down or this endpoint may be having issues. Check "          \
+          "http://status.procore.com for any known or ongoing issues.",
+          response: response,
+        )
+      end
+    end
+
+    def headers(options = {})
+      {
+        "Accepts" => "application/json",
+        "Authorization" => "Bearer #{access_token}",
+        "Content-Type" => "application/json",
+        "User-Agent" => Procore.configuration.user_agent
+      }.tap do |headers|
+        if options[:idempotency_token]
+          headers["Idempotency-Token"] = options[:idempotency_token]
+        end
+      end
+    end
+  end
+end

data/lib/procore/response.rb

@@ -0,0 +1,78 @@
+module Procore
+  # Wrapper class for a response received from the Procore API. Stores the
+  # body, code, headers, and pagination information.
+  #
+  # @example Getting the details about the response.
+  #   response = client.get("projects")
+  #   response.body #=> [{ id: 5, name: "Project 5" }]
+  #   response.code #=> 200
+  #
+  # When a response returns a collection of elements, a Link Header is included
+  # in the response. This header contains one or more URLs that can be used to
+  # access more results.
+  #
+  # The possible values for pagination are:
+  #
+  #   next  URL for the immediate next page of results.
+  #   last  URL for the last page of results.
+  #   first URL for the first page of results.
+  #   prev  URL for the immediate previous page of results.
+  #
+  # @example Using pagination
+  #   first_page = client.get("projects")
+  #
+  #   # The first page will only have URLs for :next & :last
+  #   first_page.pagination[:first]
+  #     #=> nil
+  #   first_page.pagination[:next]
+  #     #=> "projects?per_page=20&page=2"
+  #
+  #   # Any other page will have all keys
+  #   next_page = client.get(first_page.pagination[:next])
+  #   next_page.pagination[:first]
+  #     #=> "projects?per_page=20&page=1"
+  #
+  #   # The last page will only have URLs for :first & :next
+  #   last_page = client.get(first_page.pagination[:last])
+  #   last_page.pagination[:last]
+  #     #=> nil
+  class Response
+
+    # @!attribute [r] headers
+    #   @return [Hash<String, String>] Raw headers returned from Procore API.
+    # @!attribute [r] code
+    #   @return [Integer] Status Code returned from Procore API.
+    # @!attribute [r] pagination
+    #   @return [Hash<Symbol, String>] Pagination URLs
+    attr_reader :headers, :code, :pagination, :request
+
+    def initialize(body:, headers:, code:, request:)
+      @code = code
+      @headers = headers
+      @pagination = parse_pagination
+      @request = request
+      @raw_body = !body.to_s.empty? ? body : "{}".to_json
+    end
+
+    # @return [Array<Hash>, Hash] Ruby representation of JSON response. Hashes are
+    #   with indifferent access
+    def body
+      @body ||= parse_body
+    end
+
+    private
+
+    attr_reader :raw_body
+
+    def parse_body
+      JSON.parse(raw_body, object_class: HashWithIndifferentAccess)
+    end
+
+    def parse_pagination
+      headers["link"].to_s.split(", ").map(&:strip).inject({}) do |links, link|
+        url, name = link.match(/vapid\/(.*?)>; rel="(\w+)"/).captures
+        links.merge!(name.to_sym => url)
+      end
+    end
+  end
+end

data/lib/procore/util.rb

@@ -0,0 +1,52 @@
+module Procore
+  # Collection of utility methods used within the gem.
+  module Util
+    def self.log_info(message, meta = {})
+      return if Procore.configuration.logger.nil?
+
+      meta_string = meta.map do |key, value|
+        "#{colorize(key, :cyan)}: #{colorize(value, :cyan, bold: true)};"
+      end.join(" ")
+
+      Procore.configuration.logger.info(
+        "#{colorize('Procore', :yellow)} <<- " \
+        "#{colorize(message.ljust(22), :cyan)} <<- #{meta_string}",
+      )
+    end
+
+    def self.log_error(message, meta = {})
+      return if Procore.configuration.logger.nil?
+
+      meta_string = meta.map do |key, value|
+        "#{colorize(key, :red)}: #{colorize(value, :red, bold: true)};"
+      end.join(" ")
+
+      Procore.configuration.logger.info(
+        "#{colorize('Procore', :red)} <<- " \
+        "#{colorize(message.ljust(22), :red)} <<- #{meta_string}",
+      )
+    end
+
+    def self.colorize(text, color, bold: false)
+      mode = bold ? 1 : 0
+      foreground = 30 + COLOR_CODES.fetch(color)
+      background = 40 + COLOR_CODES.fetch(:default)
+
+      "\033[#{mode};#{foreground};#{background}m#{text}\033[0m"
+    end
+    private_class_method :colorize
+
+    COLOR_CODES = {
+      black: 0,
+      red: 1,
+      green: 2,
+      yellow: 3,
+      blue: 4,
+      magenta: 5,
+      cyan: 6,
+      white: 7,
+      default: 9,
+    }.freeze
+    private_constant :COLOR_CODES
+  end
+end

data/lib/procore/version.rb

@@ -0,0 +1,3 @@
+module Procore
+  VERSION = "0.6.7"
+end

data/procore.gemspec

@@ -0,0 +1,37 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "procore/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "procore"
+  spec.version       = Procore::VERSION
+  spec.authors       = ["Procore Engineering"]
+  spec.email         = ["opensource@procore.comm"]
+
+  spec.summary       = %q{Procore Ruby Gem}
+  spec.description   = %q{Procore Ruby Gem}
+  spec.homepage      = "https://github.com/procore/ruby-sdk"
+  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_development_dependency "actionpack"
+  spec.add_development_dependency "activerecord"
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "fakefs"
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "redis"
+  spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "webmock"
+
+  spec.add_dependency "httparty", "~> 0.15"
+  spec.add_dependency "oauth2", "~> 1.4"
+end