plangrade-ruby 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b4534d0455ce323b5b9a3895c1cb98889da6bb52
-  data.tar.gz: ad8e35b7ce70f104c6981c7d78394a3ebcfa2113
+  metadata.gz: f586e34e9b14bdbf1876bf3ef5a529796c851ac7
+  data.tar.gz: 26ddeaa6b6ede4f906b6e3373b19530f55fa8836
 SHA512:
-  metadata.gz: 79a7c8509b7571d148eedc7de8ca6e29068f922f7d7097134e1963bdd608697cba738083c10832cfa15ea041cce9847ed8830b282e5bef49deefe87ec94ad382
-  data.tar.gz: 1f84282566199f2d4063b70f7b25ff6570a44011ea1801e7f50882867039fb46b451794cefdc77b82cc342dde652271645b979dd076fd30b4c45e24d586bdf99
+  metadata.gz: 1df7976f370ea8d7efa29844e5b4e4158ac3c4e72aa11ba2e33f0d17e03d9156288fb3231a801916fae78811edbf89d3ced681e35ee613b6e4f7841357580429
+  data.tar.gz: d333fce2d7a39b241eda7480ab5e382cb18634baa47e1675e7d757eb0615d6d05ede65af02a81b962f2c2f8bff73f550d26588bfd26da0353569ea714293960e

data/.gitignore

@@ -3,6 +3,7 @@
 .bundle
 .config
 .yardoc
+bin/
 Gemfile.lock
 InstalledFiles
 _yardoc
@@ -15,6 +16,7 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+vendor/bundle
 *.bundle
 *.so
 *.o

data/.travis.yml

@@ -0,0 +1,20 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - jruby
+
+branches:
+  only:
+    - master
+before_install:
+  - gem update --system
+  - gem --version
+
+notifications:
+  email:
+    recipients:
+      - topherreynoso@gmail.com
+    on_failure: change
+    on_success: never

data/Gemfile

@@ -1,4 +1,11 @@
 source 'https://rubygems.org'
 
+group :test do
+  gem 'rspec', '>= 2.11'
+  gem 'simplecov', :require => false
+  gem 'coveralls', :require => false
+  gem 'webmock', '>= 1.10.1'
+end
+
 # Specify your gem's dependencies in plangrade-ruby.gemspec
 gemspec

data/README.md

@@ -3,12 +3,18 @@
 [![Code Climate](https://codeclimate.com/github/topherreynoso/plangrade-ruby/badges/gpa.svg)](https://codeclimate.com/github/topherreynoso/plangrade-ruby)
 
 Ruby wrapper for the plangrade API.
-Supports OAuth 2.0 authentication, including `refresh_token`. Read the [plangrade docs](https://docs.plangrade.com/#authentication) for more details. Additionally, this may be used in conjunction with [omniauth-plangrade](https://github.com/topherreynoso/omniauth-plangrade) in order to facilitate authentication and obtaining a valid `access_token` and `refresh_token` pair for use with this gem to access plangrade API endpoints.
+
+Supports OAuth 2.0 authentication, including `refresh_token`. Read the [plangrade docs](https://docs.plangrade.com/#authentication) for more details. 
+
+Additionally, this may be used in conjunction with [omniauth-plangrade](https://github.com/topherreynoso/omniauth-plangrade) in order to facilitate authentication and obtaining a valid `access_token` and `refresh_token` pair for use with this gem to access plangrade API endpoints.
+
+See the [plangrade-ruby-client](https://github.com/topherreynoso/plangrade-ruby-client) example for implementation of both omniauth-plangrade and plangrade-ruby.
+
 This README provides only a basic overview of how to use this gem. For more information about the API endpoints, look at the [plangrade docs](https://docs.plangrade.com/#authentication).
 
 ## Installing
 
-Add oauth2 and this line to your application's Gemfile:
+Add this line to your application's Gemfile:
 
     gem 'plangrade-ruby'
 
@@ -22,87 +28,218 @@ The plangrade API requires authentication for access to certain endpoints. Below
 
 ### Register your application
 
-Setup a plangrade client application at the [plangrade developer site](https://plangrade.com/oauth/applications). 
+Setup a plangrade client application at the [plangrade developer site](https://plangrade.com/oauth/applications).
 
-## Contributing
+### Using omniauth-plangrade to obtain an access token
 
-1. Fork it ( https://github.com/[my-github-username]/plangrade-ruby/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+You can use [omniauth-plangrade](https://github.com/topherreynoso/omniauth-plangrade) to obtain a valid access token, as demonstrated below.
 
+```ruby
+# In your redirect_uri after the user authorized access, just parse the omniauth response
+auth = request.env["omniauth.auth"]
+access_token = auth["credentials"]["token"]
+refresh_token = auth["credentials"]["refresh_token"]
+```
 
+### Using plangrade-ruby OAuth2 Client to obtain an access token
 
-plangrade OAuth2 strategy for OmniAuth.  
-Supports the OAuth 2.0 server-side and client-side flows. Read the plangrade docs for more details: [docs.plangrade.com](https://docs.plangrade.com/#authentication). Additionally, this may be used in conjunction with [plangrade-ruby](https://github.com/topherreynoso/plangrade-ruby) in order to refresh tokens and access plangrade API endpoints.
+This gem comes bundled with an OAuth2 wrapper that provides convenience methods for getting through the OAuth2 flow.
 
-## Installing
+```ruby
+# Be sure to require plangrade in any controller where you utilize plangrade-ruby
+require 'plangrade'
 
-Add omniauth-oauth2 and this line to your application's Gemfile:
+# Begin by getting the authorization url
+plangrade_client = Plangrade::OAuth2Client.new(ENV['PLANGRADE_CLIENT_ID'], ENV['PLANGRADE_CLIENT_SECRET'])
+auth_url = plangrade_client.webserver_authorization_url(:redirect_uri => 'your_redirect_uri')
+```
 
-    gem 'omniauth-plangrade'
+After the user follows the link created above and authorizes your app, they will be redirected to your `redirect_uri`, with a code in the params that you can use to obtain an access token.
 
-Then execute:
+```ruby
+plangrade_client = Plangrade::OAuth2Client.new(ENV['PLANGRADE_CLIENT_ID'], ENV['PLANGRADE_CLIENT_SECRET'])
+response = plangrade_client.exchange_auth_code_for_token({:params => {:code => params[:code], :redirect_uri => 'your_redirect_uri'}})
+token = JSON.parse response.body
+access_token = token["access_token"]
+refresh_token = token["refresh_token"]
+```
 
-    $ bundle install
+You may want to store the `access_token` since it is good for two hours. You may also want to store the `refresh_token` since it can be used to get a new `access_token` at any time, so long as the user does not revoke your app's authorization.
+
+### Using a stored `refresh_token` to obtain an access token
+
+This gem also allows you to use a `refresh_token` to obtain a new `access_token`.
+
+```ruby
+# Set up a plangrade OAuth2 client and retrieve your refresh_token
+plangrade_client = Plangrade::OAuth2Client.new(ENV['PLANGRADE_CLIENT_ID'], ENV['PLANGRADE_CLIENT_SECRET'])
+response = plangrade_client.refresh_access_token({:params => {:refresh_token => 'your_refresh_token'}})
+token = JSON.parse response.body
+access_token = token["access_token"]
+refresh_token = token["refresh_token"]
+```
+
+### Using plangrade API client to access REST endpoints
+
+You can view the current state of the client using the `Plangrade#options` method.
+
+```ruby
+require 'plangrade'
+
+Plangrade.options
+#> {:site_url=>"https://plangrade.com", :client_id=>your_client_id, :client_secret=>your_client_secret, :access_token=>current_access_token, :http_adapter=>Plangrade::Connection, :connection_options=>{:max_redirect=>5, :use_ssl=>true}}
+```
+
+To change the configuration parameters use the `configure` method. If you set your client_id and client_secret as `ENV['PLANGRADE_CLIENT_ID']` and `ENV['PLANGRADE_CLIENT_SECRET']` then this will automatically be set for you.
+
+```ruby
+Plangrade.configure do |p|
+  p.client_id = your_client_id
+  p.client_secret = your_client_secret
+end
+```
+
+At this point the `access_token` is nil. This will need to be set and, in the next section, we will see how to do this.
 
 ## Usage
 
-`OmniAuth::Strategies::Plangrade` is simply a Rack middleware. Read the OmniAuth docs for detailed instructions: [https://github.com/intridea/omniauth](https://github.com/intridea/omniauth).
+This gem offers two way to interact with plangrade's API:
+
+1. Calling methods on `Plangrade` module.
+2. Calling methods on an instance of `Plangrade::Client`.
 
-Here's a quick example, adding the middleware to a Rails app in `config/initializers/omniauth.rb`:
+### Calling methods on the plangrade module
+
+In order for this to work, you will need to set up your `access_token`. This assumes that you already configured the client with your default options as was described above.
 
 ```ruby
-Rails.application.config.middleware.use OmniAuth::Builder do
-  provider :plangrade, ENV['PLANGRADE_CLIENT_ID'], ENV['PLANGRADE_CLIENT_SECRET']
+# Set up your access_token
+Plangrade.configure do |p|
+  p.access_token = your_access_token
 end
+
+# Get the current user
+Plangrade.current_user
 ```
 
-[See the example rails app for full examples](https://github.com/topherreynoso/plangrade-ruby-client) of both the server and client-side flows.
+### Calling methods on an instance of Plangrade::Client
+
+**Note:** Use this if you wish to create multiple client instances with different `client_id`, `client_secret`, and/or `access_token`. If your application uses a single pair of `client_id` and `client_secret` credentials, you ONLY need to specify the `access_token`.
+
+```ruby
+# Create a client instance using the access_token
+plangrade = Plangrade::Client.new(:access_token => your_access_token)
+```
 
-## Auth Hash
+Call methods on the instance.
 
-Here's an example *Auth Hash* available in `request.env['omniauth.auth']`:
+**User**
+
+Current user info
+
+```ruby
+user = plangrade.current_user
+user_name = user[:name]
+```
+
+Create new user
 
 ```ruby
-{
-  :provider => 'plangrade',
-  :uid => '1234567',
-  :info => {
-    :name => 'Compliance Man',
-    :email => 'compliance@plangrade.com',
-  },
-  :credentials => {
-    :token => 'ABCDEF...', # OAuth 2.0 access_token, which you may wish to store
-    :refresh_token => 'ABCDEF...', #OAuth 2.0 refresh_token, which you may wish to store
-    :expires_at => 1321747205, # when the access token expires (it always will)
-    :expires => true # this will always be true
-  },
-  :extra => {
-    :raw_info => {
-      :id => '1234567',
-      :name => 'Compliance Man',
-      :email => 'compliance@plangrade.com',
-    }
-  }
-}
+new_user_id = plangrade.create_user(params)
 ```
 
-### How it Works
+Update user
 
-The client-side flow is supported by parsing the authorization code from the signed request which plangrade places in a cookie.
+```ruby
+updated_user = plangrade.update_user(id, params)
+```
+
+Delete user
+
+```ruby
+plangrade.delete_user(id)
+```
+
+**Companies**
+
+Create new company
+
+```ruby
+new_company_id = plangrade.create_company(params)
+```
+
+Get company info
+
+```ruby
+company = plangrade.get_company(id)
+```
+
+Get all of a user's companies
+
+```ruby
+companies = plangrade.all_companies
+```
+
+Update company
+
+```ruby
+updated_company = plangrade.update_company(id, params)
+```
+
+Delete company
+
+```ruby
+plangrade.delete_company(id)
+```
+
+**Participants**
+
+Create new participant
+
+```ruby
+new_participant_id = plangrade.create_participant(params)
+```
+
+Get participant info
+
+```ruby
+participant = plangrade.get_participant(id)
+```
+
+Get all of a company's participants
+
+```ruby
+participants = plangrade.all_participants(:company_id => id, params)
+```
+
+Update participant info
+
+```ruby
+updated_participant = plangrade.update_participant(id, params)
+```
+
+Archive participant
+
+```ruby
+archived_participant_id = plangrade.archive_participant(id)
+```
+
+Delete participant
+
+```ruby
+plangrade.delete_participant(id)
+```
 
-When you call `/auth/plangrade/callback`, the success callback will pass the cookie back to the server. omniauth-plangrade will see this cookie and:
+## Supported Ruby Versions
 
-1. parse it,
-2. extract the authorization code contained in it,
-3. and hit plangrade and obtain an access token which will get placed in the `request.env['omniauth.auth']['credentials']` hash.
+This library aims to support and is [tested against](https://travis-ci.org/topherreynoso/plangrade-ruby) the following Ruby versions:
 
-## Token Expiry
+1. Ruby 1.9.3
+2. Ruby 2.0.0
+3. Ruby 2.1.0
+4. jruby
 
-The expiration time of the access token you obtain is 2 hours.
-The refresh_token, however, has no expiration and may be used until a user revokes your app's access.
+This library may inadvertently work (or seem to work) on other Ruby implementations, however, support will only be provided for the versions listed above.
 
 ## License
 

data/Rakefile

@@ -1 +1,10 @@
-require "bundler/gem_tasks"
+require "bundler/gem_tasks"
+require 'rake'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.verbose = true
+end
+
+desc "Run spec"
+task :default => :spec

data/lib/plangrade/api/company.rb

@@ -6,19 +6,19 @@ module Plangrade
       end
 
       def update_company(id, opts={})
-        put("/api/v1/companies/#{id}", opts).body[:company]
+        put("/api/v1/companies/#{id}", opts)
       end
 
       def delete_company(id)
-        delete("/api/v1/companies/#{id}", opts)
+        delete("/api/v1/companies/#{id}")
       end
 
       def get_company(id)
-        get("/api/v1/companies/#{id}").body[:company]
+        get("/api/v1/companies/#{id}")
       end
 
       def all_companies(opts={})
-        get("/api/v1/companies", opts).body[:companies]
+        get("/api/v1/companies", opts)
       end
     end
   end

data/lib/plangrade/api/participant.rb

@@ -6,23 +6,24 @@ module Plangrade
       end
 
       def update_participant(id, opts={})
-        put("/api/v1/participants/#{id}", opts).body[:participant]
+        put("/api/v1/participants/#{id}", opts)
       end
 
       def delete_participant(id)
-        delete("/api/v1/participants/#{id}", opts)
+        delete("/api/v1/participants/#{id}")
       end
 
       def archive_participant(id)
-        get("api/v1/participants/archive?participant_id=#{id}")
+        get("/api/v1/participants/archive?participant_id=#{id}")
       end
 
       def get_participant(id)
-        get("/api/v1/participants/#{id}").body[:participant]
+        get("/api/v1/participants/#{id}")
       end
 
       def all_participants(opts={})
-        get("/api/v1/participants", opts).body[:participants]
+        company_id = opts[:company_id]
+        get("/api/v1/participants?company_id=#{company_id}")
       end
     end
   end

data/lib/plangrade/api/user.rb

@@ -6,15 +6,15 @@ module Plangrade
       end
 
       def update_user(id, opts={})
-        put("/api/v1/users/#{id}", opts).body[:user]
+        put("/api/v1/users/#{id}", opts)
       end
 
       def delete_user(id)
-        delete("/api/v1/users/#{id}", opts)
+        delete("/api/v1/users/#{id}")
       end
 
       def current_user
-      	get('/api/v1/me').body
+      	get('/api/v1/me')
       end
     end
   end

data/lib/plangrade/oauth2_client.rb

@@ -44,6 +44,7 @@ module Plangrade
     #
     # >> client = PlangradeClient.new(config)
     # >> client.exchange_auth_code_for_token({
+    #      :code => '123456789'
     #      :redirect_uri => 'http://localhost:3000/auth/plangrade/callback',
     #    })
     #

data/lib/plangrade/resources/company.rb

@@ -9,7 +9,7 @@ module Plangrade
         new(:id => id)
       end
 
-      attr_accessor_deffered :id, :name, :ein, :grade
+      attr_accessor_deffered :name, :ein, :grade
 
       def update!(params)
         api_handler.update_company(@id, params)

data/lib/plangrade/resources/participant.rb

@@ -1,6 +1,6 @@
 module Plangrade
   module Resources
-    class Participants < Plangrade::Resources::Base
+    class Participant < Plangrade::Resources::Base
 
       def self.create(company_id, first_name, last_name, street1, street2, city, state, zip, dob, ssn, email, phone, employee_id)
 
@@ -13,7 +13,7 @@ module Plangrade
         new(:id => id)
       end
 
-      attr_accessor_deffered :id, :company_id, :employee_id, :first_name, :last_name, :street1, :street2, :city, :state, :zip,
+      attr_accessor_deffered :company_id, :employee_id, :first_name, :last_name, :street1, :street2, :city, :state, :zip,
       :dob, :ssn, :email, :phone
 
       def update!(params)

data/lib/plangrade/resources/user.rb

@@ -2,8 +2,8 @@ module Plangrade
   module Resources
     class User < Plangrade::Resources::Base
 
-      def self.current
-        result = api_handler.current_resource_owner
+      def self.current_user
+        result = api_handler.current_user
         return nil unless result.success?
         new(result.body)
       end
@@ -15,7 +15,7 @@ module Plangrade
         new(:id => id)
       end
 
-      attr_accessor_deffered :id, :email, :name
+      attr_accessor_deffered :email, :name
 
       def update!(params)
         api_handler.update_user(@id, params)

data/lib/plangrade/ruby/version.rb

@@ -1,5 +1,5 @@
 module Plangrade
   module Ruby
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/plangrade-ruby.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.summary       = %q{plangrade API client}
   spec.description   = %q{A ruby wrapper for accessing plangrade's REST API}
   spec.homepage      = "https://github.com/topherreynoso/plangrade-ruby"
-  spec.license       = "MIT"
+  spec.licenses      = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
@@ -21,19 +21,15 @@ Gem::Specification.new do |spec|
   spec.cert_chain    = ['certs/public.pem']
   spec.signing_key   = File.expand_path("~/.ssh/gem-private_key.pem") if $0 =~ /gem\z/
 
-  spec.add_development_dependency "bundler", "~> 1.6"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "minitest"
-  spec.add_development_dependency "vcr"
-  spec.add_development_dependency "webmock"
-
-  spec.add_dependency "faraday"
-  spec.add_dependency "json"
   spec.add_dependency 'oj', '~> 2.0'
   spec.add_dependency 'multi_json', '~> 1.8'
   spec.add_dependency 'rest-client', '~> 1.6'
   spec.add_dependency 'addressable', '~> 2.3'
   spec.add_dependency 'oauth2-client', '~> 2.0'
 
-  spec.post_install_message = %q{ Thanks for installing! For API help go to http://docs.plangrade.com }
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'simplecov', '>= 0.8'
+  spec.add_development_dependency 'webmock', '>= 1.9'
+  spec.add_development_dependency 'yard', '>= 0.8'
 end

data/spec/api/company_spec.rb

@@ -0,0 +1,72 @@
+# -*- encoding: utf-8 -*-
+
+# Copyright (c) Microsoft Corporation
+# All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY
+# IMPLIED WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR
+# PURPOSE, MERCHANTABLITY OR NON-INFRINGEMENT.
+#
+# See the Apache Version 2.0 License for specific language governing
+# permissions and limitations under the License.
+
+require File.expand_path('../../spec_helper', __FILE__)
+require 'ostruct'
+
+describe Plangrade::Api::Company do
+
+  before :all do
+    @client = Plangrade::Client.new(
+      :site_url     => 'https://plangrade.com',
+      :client_id     => 'PRbTcg9qjgKsp4jjpm1pw',
+      :client_secret => 'Xn7kp7Ly0TCY4GtZWkmSsqGEPg10DmMADyjWkf2U',
+      :access_token  => 'TolNOFka9Uls2DxahNi78A'
+    )
+  end
+
+  subject { @client }
+
+  describe 'create_company' do
+    it 'makes an http request' do
+      params = {:name => 'plangrade, llc', :ein => '123456789'}
+      @client.should_receive(:post).with('/api/v1/companies', params)
+      @client.create_company(params)
+    end
+  end
+
+  describe 'update_company' do
+    it 'makes an http request' do
+      params = {:name => 'plangrade, inc'}
+      @client.should_receive(:put).with('/api/v1/companies/1', params)
+      @client.update_company(1, params)
+    end
+  end
+
+  describe 'delete_company' do
+    it 'makes an http request' do
+      @client.should_receive(:delete).with('/api/v1/companies/1')
+      @client.delete_company(1)
+    end
+  end
+
+  describe 'get_company' do
+    it 'makes an http request' do
+      @client.should_receive(:get).with('/api/v1/companies/1')
+      @client.get_company(1)
+    end
+  end
+
+  describe 'all_companies' do
+    it 'makes an http request' do
+      @client.should_receive(:get).with('/api/v1/companies', {:page => 1, :letter => 'm'})
+      @client.all_companies({:page => 1, :letter => 'm'})
+    end
+  end
+end