procore 0.6.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 318aae4eb7a76a5bad258a57d2614bde20e5b35b56f2e0d05a5d8d4ea2dc1aa6
+  data.tar.gz: 3546d5ca61534836b1ef63d10bf95e5f26db586a8873be3466a87e82824c02d9
+SHA512:
+  metadata.gz: 0b5460652ebaf4c1b73925333d58345ba1483d7e5fd92403ac9c756209430918c4f73d819ee02328be314e91e030e48df13dfce913c3ce01eb6eb15a780ba248
+  data.tar.gz: 6d9340c15d1d28018e88019b60bccf5e2211a1a976294d1c293738330d1b853794daf08463d6842c96b2a1ef0b88d7f8704d1ef5842c7d84f6f48005f3c3d65e

data/.gitignore

@@ -0,0 +1,11 @@
+.yardopts
+
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,27 @@
+language: ruby
+rvm:
+  - 2.3
+  - 2.4
+  - 2.5
+
+services:
+  - redis-server
+
+before_install:
+  - gem update --system
+
+cache: bundler
+
+script: bundle exec rake
+
+deploy:
+  provider: rubygems
+  api_key:
+    secure: GYH7nTi2D9ZwbCP+JYSgHceDUvZT9RQSP6yXFndwSyxdiSmB6wfq6EtoH4Wpznd6ALT6IxrtbR4aftTI9DO6HPq+PVO6NdxjkdlbdxxAqRQJBAwFwFATT8jCuuDjGPLf8PF0ouzcMvAIdIgHypwmLdevWdEMomWdRWlm1UFP/0C3RDjY1v04XDrRb+fEagPNnzMDCcO352nyFm06jnCq/ezjCRXBvNtHTZeqd7t9pbNw7gtYebZ3b9hfd4IIa68budeh+URygiPnNNWr6TCjO95IuHIeMDele3tir0KzqVBNsVAqEb7WpB26rf1JgneAoYZwVMFh+hk09cs68EbIELD4MX6/PzEUz2Ws20dIMjs1pcDtlw35ixoEpwC/vz2qVJyMRYXg8af5rpsZkKXRl7QP2LrX+xSEt4LiRnylj4PaRZWu1gvhC7fsCHXEM3mW3WlXFUmb9W4Jv8VooqOJtGhpD9Qs9pYtTOgJoEmYqttbuCaiYKaiPutBY4+t+t2ZmyCopv41nkjv/UCWXfo11ew1qK0rxDJVE2/JYTUDZ+zuHypTf2lHCWjyP65vGwBnmdixLnEMCUOkzKUmqFR4kAE6jRMEhtki4fTlFSIHJGM5oIXeRXDR43NIh7xWNvhl7lHkwWoRA0BfSITtvO8k0SefGnFwhNfOglQ/GKfyAaY=
+  gem: procore
+  on:
+    tags: true
+    repo: procore/ruby-sdk
+
+notifications:
+  email: false

data/CHANGELOG.md

@@ -0,0 +1,46 @@
+## Unreleased
+
+## 0.6.7 (January 04, 2018)
+
+* Allow gem to be pushed to RubyGems
+
+## 0.6.6 (January 04, 2018)
+
+* Move to using TravisCI
+* Publish to RubyGems
+
+## 0.6.5 (January 04, 2018)
+
+* Add response to `OAuthError`
+
+## 0.6.4 (December 15, 2017)
+
+* Fix issue with passing request into `Procore::Response`.
+
+  *Michael Stock*
+
+## 0.6.3 (December 11, 2017)
+
+*  Fix issue with client credentials by forcing the usage of request body
+   for sending `client_id` and `client_secret`
+
+   *Michael Stock*
+
+## 0.6.2 (December 6, 2017)
+
+*  Fix session store not saving off the optional key attribute
+
+   PR #2 - https://github.com/procore/ruby-sdk/pull/2
+
+   *Patrick Koperwas*
+
+## 0.6.1 (December 6, 2017)
+
+*  Change error class for 404s.
+
+   Previously a 404 would raise a Procore::InvalidRequestError. Now, a 404 will
+   raise a Procore::NotFoundError,
+
+   PR #1 - https://github.com/procore/ruby-sdk/pull/1
+
+   *Patrick Koperwas*

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in procore.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Patrick Koperwas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,407 @@
+# Procore Gem
+
+[![Build Status](https://travis-ci.org/procore/ruby-sdk.svg?branch=move-to-travis)](https://travis-ci.org/procore/ruby-sdk)
+
+## Installation & Usage
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "procore"
+```
+
+## Making Requests
+
+At the core of the gem is the `Client` class. Clients are initialized with a
+`client_id` and `client_secret` which can be obtained by signing up for
+Procore's [Developer Program](https://developers.procore.com/).
+
+A client requires a store. A store manages a particular user's access token.
+Stores automatically manage tokens for you - refreshing, revoking and storage
+are abstracted away to make your code as simple as possible. There are several
+different [types of stores](#stores) available to you.
+
+The client class exposes `#get`, `#post`, `#patch` and `#delete` methods to you.
+
+```ruby
+get(path, query = {})
+post(path, body = {}, options = {})
+patch(path, body = {}, options = {})
+delete(path, query = {})
+```
+
+All paths are relative - the gem will handle expanding `client.get("me")` to
+`https://app.procore.com/vapid/me`.
+
+Example Usage:
+
+```ruby
+store = Procore::Auth::Stores::Session.new(session: session)
+client = Procore::Client.new(
+  client_id: "client id",
+  client_secret: "client secret",
+  store: store
+)
+
+# Get the current user's companies
+companies = client.get("companies")
+
+companies.first[:name] #=> "Procore Company 1"
+```
+
+## Usage
+
+The first step is to place the user's token into the store. For this example,
+the tokens will be stored in the Rails session. In the controller action that
+handles the end of the [OAuth 2.0
+Flow](https://developers.procore.com/documentation/oauth-introduction) add the
+following code:
+
+```ruby
+def handle_callback
+  if auth_hash.blank?
+    redirect_to '/auth/procore'
+  else
+    auth_hash = request.env['omniauth.auth']
+
+    # Create a new token to save into a store
+    token = Procore::Auth::Token.new(
+      access_token: auth_hash["credentials"]["token"]
+      refresh_token: auth_hash["credentials"]["refresh_token"],
+      expires_at: auth_hash["credentials"]["expires_at"]
+    )
+
+    store = Procore::Auth::Stores::Session.new(session: session)
+    store.save(token)
+
+    redirect_to root_path
+  end
+end
+```
+
+With the user's token stored, requests can be made from anywhere in the
+application that has access to the Rails session.
+
+```ruby
+client = Procore::Client.new(
+  client_id: Rails.application.secrets.procore_app_id,
+  client_secret: Rails.application.secrets.procore_app_secret,
+  store: Procore::Auth::Stores::Session.new(session: session)
+)
+
+client.get("me")
+```
+
+## Error Handling
+
+The Procore Gem raises errors whenever a request returns a non `2xx` response.
+Errors return both a message detailing the error and an instance of a
+`Response`.
+
+```ruby
+begin
+  # Use Procore Gem to make requests
+  client.get("projects")
+
+rescue Procore::RateLimitError => e
+  # 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.
+
+rescue Procore::NotFoundError => e
+  # Raised when the request 404's
+
+rescue Procore::InvalidRequestError => e
+  # Raised when the request is incorrectly formated. Possible causes: missing
+  # required parameters or sending a request to access a non-existent resource.
+
+rescue Procore::OAuthError => e
+  # Raised whenever there is a problem with OAuth. Possible causes: required
+  # credentials are missing or an access token failed to refresh.
+
+rescue Procore::AuthorizationError => e
+  # Raised when the request is attempting to access a resource the token's
+  # owner does not have access to.
+
+rescue Procore::APIConnectionError => e
+  # Raised when the gem cannot connect to the Procore API. Possible causes:
+  # Procore is down or the network is doing something funny.
+
+rescue Procore::ServerError => e
+  # Raised when a Procore endpoint returns a 500x resonse code.
+
+rescue Procore::Error => e
+  # Generic catch all error.
+
+rescue => e
+  # Something unrelated to Procore errored.
+end
+```
+
+Note that all errors inherit from `Procore::Error`, so if you do not need to
+handle each error uniquely you can just rescue from this base class to catch all
+errors generated by this gem.
+
+```ruby
+begin
+  client.get("projects")
+rescue Procore:Error => e
+  # Something went wrong.
+
+  # Print the error class
+  puts e.class
+
+  # Print the error message
+  puts e.message
+
+  # Print the HTTP code
+  puts e.response.code
+
+  # Print the json error response
+  puts e.response.errors
+
+  # Print the headers
+  puts e.response.headers
+end
+```
+
+## Pagination
+Endpoints which return multiple objects (a collection) will include pagination
+information. The `Response` object has a `#pagination` method that will return
+a hash which may conditionally contain the following keys:
+
+```
+: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.
+```
+
+For example, on the first page of results the `#pagination` method will look
+like:
+
+```ruby
+response.pagination
+
+{
+  next: "projects?per_page=100&page=2",
+  last: "projects?per_page=100&page=5"
+}
+```
+
+The `next` value will return the second page of results - which is expected as
+all paginated responses start on page 1. The `last` value ends on page 5, so
+there are another 4 pages to consume in order to get all the possible results.
+
+### Navigating Through Paginated Results
+
+To get the next page of results, just pass the url into `client#get`. You may
+want to guard against the next page being potentially empty.
+
+```ruby
+first_page = client.get("projects")
+
+if first_page.pagination[:next]
+  next_page = client.get(first_page.pagination[:next])
+end
+
+puts next_page.pagination
+
+{
+  first: "projects?per_page=100&page=1",
+  next: "projects?per_page=100&page=3",
+  prev: "projects?per_page=100&page=1",
+  last: "projects?per_page=100&page=5"
+}
+```
+
+### Change Number of Results
+
+You can pass a `per_page` query parameter in your request to change the page
+size. The pagination links will update to reflect that change.
+
+```
+first_page = client.get("projects", per_page: 250)
+
+puts first_page.pagination
+{
+  next: "projects?per_page=250&page=2",
+  last: "projects?per_page=250&page=2"
+}
+```
+
+Notice that because `per_page` has been set to 250, there are only two pages of
+results (500 resources / 250 page size = 2 pages).
+
+## Configuration
+
+The Procore Gem exposes a configuration with several options.
+
+```ruby
+# config/initializes/procore.rb
+
+require "procore"
+Procore.configure do |config|
+  # Base API host name. Alter this depending on your environment - in a
+  # staging or test environment you may want to point this at a sandbox
+  # instead of production.
+  config.host = ENV.fetch("PROCORE_BASE_API_PATH", "https://app.procore.com")
+
+  # Integer: Number of times to retry a failed API call. Reasons an API call
+  # could potentially fail:
+  # 1. Service is briefly down or unreachable
+  # 2. Timeout hit - service is experiencing immense load or mid restart
+  # 3. Because computers
+  #
+  # Defaults to 1 retry. Would recommend 3-5 for production use.
+  # Has exponential backoff - first request waits a 1.5s after a failure,
+  # next one 2.25s, next one 3.375s, 5.0, etc.
+  config.max_retries = 3
+
+  # Float: Threshold for canceling an API request. If a request takes longer
+  # than this value it will automatically cancel.
+  config.timeout = 5.0
+
+  # Instance of a Logger. This gem will log information about requests,
+  # responses and other things it might be doing. In a Rails application it
+  # should be set to Rails.logger
+  config.logger = Rails.logger
+
+  # String: User Agent sent with each API request. API requests must have a user
+  # agent set. It is recomended to set the user agent to the name of your
+  # application.
+  config.user_agent = "MyAppName"
+end
+```
+
+## Stores
+
+Stores contain logic for accessing, storing, and managing access tokens. The
+Procore API uses expiring tokens - this gem abstracts away the need to manually
+refresh tokens.
+
+Available stores:
+
+### Session Store
+
+Options: `session`: Instance of a Rails session
+
+For applications that want to keep access tokens in the user's session.
+
+```ruby
+store = Procore::Auth::Stores::Session.new(session: session)
+```
+
+### Redis Store
+
+Options: `redis`: Instance of Redis
+Options: `key`: Unique identifier to an access token
+
+For applications which want to store access tokens in Redis. There's two
+required options, `redis` which is an instance of a Redis connection, and `key`
+which is a unique key which will be used to save / retrieve an access token.
+They key will usually be the id of the current user.
+
+```ruby
+store = Procore::Auth::Stores::Redis.new(redis: Redis.new, key: current_user.id)
+```
+
+### ActiveRecord Store
+
+Options: `object`: Instance of an ActiveRecord model.
+
+For applications that store access token information on some user object.
+
+The following columns **must** exist on the model you pass in:
+`access_token`, `refresh_token` and `expires_at`.
+
+```ruby
+store = Procore::Auth::Stores::ActiveRecord.new(object: current_user)
+```
+
+### File Store
+
+Options: `path`: Path to a file to store access tokens
+Options: `key`: Unique identifier to an access token
+
+Intended for command line applications, the File Store saves access token
+information to disk. This way a user can run a CLI without needing to
+authenticate every single command.
+
+```ruby
+store = Procore::Auth::Stores::File.new(path: "./tokens.yml", key: current_user.id)
+```
+
+### Memory Store
+
+Options: `key`: Unique identifier to an access token
+
+The most basic store - a token is kept in memory for the duration of a request.
+This store type is not recommended for application usage - it is meant to be
+used in tests.
+
+```ruby
+store = Procore::Auth::Stores::Memory.new(key: current_user.id)
+```
+
+## Full Example
+
+```ruby
+# In controller, callback from oauth
+def handle_callback
+  if auth_hash.blank?
+    redirect_to '/auth/procore'
+  else
+    auth_hash = request.env['omniauth.auth']
+
+    # Create a new token to save into a store
+    token = Procore::Auth::Token.new(
+      access_token: auth_hash["token"]
+      refresh_token: auth_hash["refresh_token"],
+      expires_at: auth_hash["expires_at"]
+    )
+
+    store = Procore::Auth::Stores::Session.new(session: session)
+    store.save(token)
+
+    redirect_to root_path
+  end
+end
+
+# Somewhere else in the application
+class ProjectsController
+  def index
+    @projects = client.get("projects", company_id: params[:company_id])
+  end
+
+  private
+
+  def client
+    @client ||= Procore::Client.new(
+      client_id: Rails.application.secrets.procore_client_id,
+      client_secret: Rails.application.secrets.procore_client_secret,
+      store: Procore::Auth::Stores::Session.new(session: session)
+    )
+  end
+end
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](http://opensource.org/licenses/MIT).
+
+## About Procore
+
+<img
+  src="https://www.procore.com/images/procore_logo.png"
+  alt="Procore Logo"
+  width="250px"
+/>
+
+The Procore Gem is maintained by Procore Technologies.
+
+Procore - building the software that builds the world.
+
+Learn more about the #1 most widely used construction management software at
+[procore.com](https://www.procore.com/)