whiplash-app 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9acc3cba8b3e4cef52a2068e9fe3f16c81d7815f
-  data.tar.gz: c351232810577e3f357512c9c4b7e550bf0dbb2b
+  metadata.gz: 5b252f73755dcd2e6cc7d907d0009393a0661993
+  data.tar.gz: d38c18badde2221b2c9de962db701ca54a486739
 SHA512:
-  metadata.gz: f4bc91939f74965a430b4c5d6f21ca888d568fe9e31fa3e9ef67d94f45324768f983693e8db756836408768ad40cfa7fd9047ffa352fcaabcc88c44332dcc02a
-  data.tar.gz: 25b613c592e8c728bf9b447624df347e2989bf2b04e2109b371ea200ae57a494883d2382c2a90b56abd8d4e62a56e43bdcb30765aea81b68e5b99d0cb44493f9
+  metadata.gz: ae66c0ded848674943ad97c2781236569d4d3cfff515ad30218b7025028660ce0cf10374f243d516b553781ca3a023460ca4b25e21713225b0a135c3ec6708cb
+  data.tar.gz: '04845cdd6a2eb36c1f05b43932f11bf25c6d32d0c91fbb74db2cb7f23b5ca9d84d3f8719fe58926831a4d26c1c07119aa03d3b74a92b7f1528f706fa169b37f1'

data/.gitignore

@@ -7,3 +7,5 @@
 /pkg/
 /spec/reports/
 /tmp/
+.env
+.ruby-version

data/README.md

@@ -22,7 +22,27 @@ Or install it yourself as:
 
 ## Usage
 
-###Authentication
+**NOTE: 0.4.0 introduces a breaking change and is NOT backward compatible with previous versions.**
+
+To upgrade from < 0.4.0, you need to make two small changes:
+1. `Whiplash::App` must now be instantiated.
+2. Tokens are **not** automatically refreshed
+
+Before:
+```ruby
+api = Whiplash::App
+```
+
+After:
+```ruby
+api = Whiplash::App.new
+api.refresh_token! # Since you don't have one yet
+api.token # Confirm you've got a token
+. . .
+api.refresh_token! if api.token_expired?
+```
+
+### Authentication
 In order to authenticate, make sure the following `ENV` vars are set:
 
 ```ruby
@@ -30,85 +50,90 @@ ENV["WHIPLASH_CLIENT_ID"]
 ENV["WHIPLASH_CLIENT_SECRET"]
 ENV["WHIPLASH_CLIENT_SCOPE"]
 ```
-Once those are set, authentication is handled in app.  While authentication is
-mostly baked into the calls, there is a method that allows for getting the app's
-token from the main app: `Whiplash::App.token`.
+
+Once those are set, authentication is handled in app.
+
+### Oauth Client Credentials
+You can authenticate using Oauth Client Credentials (i.e. auth an entire app).
+You probably want this for apps that work offline, _on behalf_ of users or customers, or that don't work at the user/customer-level at all.
+
+```ruby
+api = Whiplash::App.new
+api.refresh_token! # Since you don't have one yet
+api.token # Confirm you've got a token
+```
+
+### Oauth Authorization Code
+You can also authenticate using Oauth Authorization Code (i.e. auth an individual user). This is most common for user-facing app's with a front end.
+
+```ruby
+# Authenticate using Devise Omniauthenticateable strategy; you'll get oauth creds back as a hash
+api = Whiplash::App.new(oauth_credentials_hash)
+api.token # Confirm you've got a token
+```
 
 ### API URL
 In order to set your api url, you can use the following environment URL:
 ```
 ENV["WHIPLASH_API_URL"]
 ```
-If it isn't set, then the API URL defaults to either `https://testing.whiplashmerch.com` (test or dev environment) or `https://www.whiplashmerch.com` (prod environment).
+If it isn't set, then the API URL defaults to either `https://sandbox.getwhiplash.com` (test or dev environment) or `https://www.getwhiplash.com` (prod environment).
+
+### Sending Customer ID and Shop ID headers
+You can send the headers in `headers` array, like `{customer_id: 123, shop_id: 111}`.
+Alternatively, you can set them on instantiation like `Whiplash::App.new(token, {customer_id: 123, shop_id: 111})`.
 
-###Rails AR type calls
+### Rails AR type calls
 
 In order to make the use of the gem seem more "AR-ish", we've added AR oriented methods that can be used for basic object creation/deletion/updating/viewing. The basic gist of these AR style CRUD methods is that they will all follow the same pattern.  If you are performing a collection action, such as `create` or `find`, the pattern is this:
 
 ```ruby
-Whiplash::App.create(resource, params, headers)
+api.create(resource, params, headers)
 ```
 
 For member actions, such as `show`, or `destroy` methods, the pattern is this:
 
 ```ruby
-Whiplash::App.find(resource, id, headers)
-Whiplash::App.destroy(resource, id, headers)
+api.find(resource, id, headers)
+api.destroy(resource, id, headers)
 ```
 
 Finally, for `update` calls, it's a mixture of those:
 
 ```ruby
-Whiplash::App.update(resource, id, params_to_update, headers)
+api.update(resource, id, params_to_update, headers)
 ```
 
 So, basic AR style calls can be performed like so:
 
 ```ruby
-Whiplash::App.find_all('orders', {}, { customer_id: 187 })
-Whiplash::App.find('orders', 1)
-Whiplash::App.create('orders', { key: "value", key2: "value" }, { customer_id: 187 } )
-Whiplash::App.update('orders', 1, { key: "value"}, { customer_id: 187 } )
-Whiplash::App.destroy('orders', 1, { customer_id: 187 } )
-Whiplash::App.count('customers') #unlike other calls, which return Faraday responses, this call returns an integer.
+api.find_all('orders', {}, { customer_id: 187 })
+api.find('orders', 1)
+api.create('orders', { key: "value", key2: "value" }, { customer_id: 187 } )
+api.update('orders', 1, { key: "value"}, { customer_id: 187 } )
+api.destroy('orders', 1, { customer_id: 187 } )
+api.count('customers')
 ```
 
-###CRUD Wrapper methods
+### CRUD Wrapper methods
 In reality, all of these methods are simply wrapper methods around simple `GET/POST/PUT/DELETE` wrappers on Faraday, so if you want to get more granular,you can also make calls that simply reference the lower level REST verb:
 
 ```ruby
-Whiplash::App.get('orders', {}, {})
+api.get('orders')
 ```
 Which will return all orders and roughly correspond to an index call. If you need to use `Whiplash::App` for nonRESTful calls, simply drop the full endpoint in as your first argument:
 
 ```ruby
-Whiplash::App.get('orders/non_restful_action', {}, {})
+api.get('orders/non_restful_action', {}, {})
 ```
 `POST`, `PUT`, and `DELETE` calls can be performed in much the same way:
 ```ruby
-Whiplash::App.post(endpoint, params, headers) #POST request to the specified endpoint passing the payload in params
+api.post(endpoint, params, headers) # POST request to the specified endpoint passing the payload in params
+api.put(endpoint, params, headers) # PUT request to the specified endpoint passing the payload in params
+api.delete(endpoint, params, headers) # DELETE request to the specified endpoint.  Params would probably just be an id.
 ```
-```ruby
-Whiplash::App.put(endpoint, params, headers) #PUT request to the specified endpoint passing the payload in params
-```
-```ruby
-Whiplash::App.delete(endpoint, params, headers) #DELETE request to the specified endpoint.  Params would probably just be an id.
-```
-
-*IMPORTANT!!!! PLEASE READ!*
-It's best if possible to use the AR style methods.  They hide a lot of issues with the way Faraday handles params.  For example, this should, in theory, work:
-```ruby
-Whiplash::App.get('orders', {id: 1}, {customer_id: 187})  
-```
-BUT, due to the way Faraday handles params, this would not, as expected, route to `orders#show` in the Whiplash App, but would instead route to `orders#index`, so it wouldn't return the expected singular order with an ID of 1, but all orders for that customer.
-
-The gem works best when the base CRUD methods are used ONLY for situations where a singular endpoint can't be reached, such as a cancel action, or uncancel, which would have to be done like so:
-```ruby
-Whiplash::App.post('orders/1/cancel', {}, {customer_id: 187})
-```
-
 
-###Signing and Verifying.
+### Signing and Verifying.
 `whiplash-app` supports signing and verifying signatures like so:
 ```ruby
 Whiplash::App.signature(request_body)
@@ -118,10 +143,9 @@ and verifications are done like so:
 Whiplash::App.verified?(request)
 ```  
 
-###Caching
-`whiplash-app` is Cache agnostic, relying on the `moneta` gem to provide that
-interface.  However, if you intend to specify `REDIS` as your key-value store of
-choice, it's dead simple.  Simply declare the following variables:
+### Caching
+`whiplash-app` is Cache agnostic, relying on the `moneta` gem to provide a local store, if needed.  
+However, if you intend to specify `REDIS` as your key-value store of choice, it's dead simple.  Simply declare the following variables:
 ```
 ENV["REDIS_HOST"]
 ENV["REDIS_PORT"]
@@ -130,6 +154,19 @@ ENV["REDIS_NAMESPACE"]
 ```
 If those are provided, `moneta` will use your redis connection and will namespace your cache storage under the redis namespace.  By default, if you do not declare a `REDIS_NAMESPACE` value, the app will default to the `WHIPLASH_CLIENT_ID`.
 
+**For user-facing apps, best practice is to store the `oauth_credentials_hash` in a session variable.**
+
+### Gotchas
+Due to the way Faraday handles params, this would not, as expected, route to `orders#show` in the Whiplash App, but would instead route to `orders#index`, so it wouldn't return the expected singular order with an ID of 1, but all orders for that customer.
+```ruby
+api.get('orders', {id: 1}, {customer_id: 187})  
+```
+Instead, you'd want to do:
+```ruby
+api.get('orders/1', {}, {customer_id: 187})  
+```
+
+
 ## 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.

data/lib/whiplash/app/api_config.rb

@@ -1,5 +1,5 @@
 module Whiplash
-  module App
+  class App
     module ApiConfig
 
       def api_url

data/lib/whiplash/app/caching.rb

@@ -1,7 +1,7 @@
 require "moneta"
 require "whiplash/app/moneta/namespace"
 module Whiplash
-  module App
+  class App
     module Caching
 
       def cache_store

data/lib/whiplash/app/connections.rb

@@ -1,5 +1,5 @@
 module Whiplash
-  module App
+  class App
     module Connections
 
       def app_request(options = {})
@@ -8,6 +8,9 @@ module Whiplash
         else
           endpoint = options[:endpoint]
         end
+        options[:headers] ||= {}
+        options[:headers][:customer_id] ||= customer_id if customer_id
+        options[:headers][:shop_id] ||= shop_id if shop_id
         connection.send(options[:method],
                         endpoint,
                         options[:params],

data/lib/whiplash/app/finder_methods.rb

@@ -1,5 +1,5 @@
 module Whiplash
-  module App
+  class App
     module FinderMethods
 
       def count(resource, params = {}, headers = nil)

data/lib/whiplash/app/signing.rb

@@ -1,11 +1,6 @@
 module Whiplash
-  module App
+  class App
     module Signing
-
-      def request_body(body)
-        body.blank? ? ENV["WHIPLASH_CLIENT_ID"] : body
-      end
-
       def signature(body)
         sha256 = OpenSSL::Digest::SHA256.new
         OpenSSL::HMAC.hexdigest(sha256,
@@ -17,6 +12,11 @@ module Whiplash
         request.headers["X-WHIPLASH-SIGNATURE"] == signature(body)
       end
 
+      private
+
+      def request_body(body)
+        body.blank? ? ENV["WHIPLASH_CLIENT_ID"] : body
+      end
     end
   end
 end

data/lib/whiplash/app/version.rb

@@ -1,5 +1,5 @@
 module Whiplash
-  module App
-    VERSION = "0.3.1"
+  class App
+    VERSION = "0.4.0"
   end
 end

data/lib/whiplash/app.rb

@@ -8,42 +8,71 @@ require "oauth2"
 require "faraday_middleware"
 
 module Whiplash
+  class App
+    include Whiplash::App::ApiConfig
+    include Whiplash::App::Caching
+    include Whiplash::App::Connections
+    include Whiplash::App::FinderMethods
+    extend Whiplash::App::Signing
 
-  module App
-    class << self
-      include Whiplash::App::ApiConfig
-      include Whiplash::App::Caching
-      include Whiplash::App::Connections
-      include Whiplash::App::FinderMethods
-      include Whiplash::App::Signing
+    attr_accessor :customer_id, :shop_id, :token
 
-      attr_accessor :customer_id, :shop_id
+    def initialize(token=nil, options={})
+      opts = options.with_indifferent_access
+      @token = format_token(token) unless token.nil?
+      @customer_id = options[:customer_id]
+      @shop_id = options[:shop_id]
+    end
 
-      def client
-        OAuth2::Client.new(ENV["WHIPLASH_CLIENT_ID"], ENV["WHIPLASH_CLIENT_SECRET"], site: api_url)
-      end
+    def client
+      OAuth2::Client.new(ENV["WHIPLASH_CLIENT_ID"], ENV["WHIPLASH_CLIENT_SECRET"], site: api_url)
+    end
 
-      def connection
-        out = Faraday.new [api_url, "api/v2"].join("/") do |conn|
-          conn.request :oauth2, token, token_type: "bearer"
-          conn.request :json
-          conn.response :json, :content_type => /\bjson$/
-          conn.use :instrumentation
-          conn.adapter Faraday.default_adapter
-        end
-        return out
+    def connection
+      out = Faraday.new [api_url, "api/v2"].join("/") do |conn|
+        conn.request :oauth2, token.token, token_type: "bearer"
+        conn.request :json
+        conn.response :json, :content_type => /\bjson$/
+        conn.use :instrumentation
+        conn.adapter Faraday.default_adapter
       end
+      return out
+    end
+
+    def token=(oauth_token)
+      instance_variable_set("@token", format_token(oauth_token))
+    end
 
-      def refresh_token!
-        oauth_token = client.client_credentials.get_token(scope: ENV["WHIPLASH_CLIENT_SCOPE"])
-        new_token = oauth_token.token
+    def refresh_token!
+      if token.blank? # If we're storing locally, grab a new token and cache it
+        access_token = client.client_credentials.get_token(scope: ENV["WHIPLASH_CLIENT_SCOPE"])
+        new_token = access_token.to_hash
         cache_store["whiplash_api_token"] = new_token
+      else
+        access_token = token.refresh!
       end
+      self.token = access_token
+    end
+
+    def token_expired?
+      return token.expired? unless token.blank?
+      return true unless cache_store.has_key?("whiplash_api_token")
+      return true if cache_store["whiplash_api_token"].blank?
+      false
+    end
 
-      def token
-        refresh_token! unless cache_store["whiplash_api_token"]
-        return cache_store["whiplash_api_token"]
+    private
+    def format_token(oauth_token)
+      unless oauth_token.is_a?(OAuth2::AccessToken)
+        raise StandardError, "Token must either be a Hash or an OAuth2::AccessToken" unless oauth_token.is_a?(Hash)
+        oauth_token['expires'] = oauth_token['expires'].to_s # from_hash expects 'true'
+        if oauth_token.has_key?('token')
+          oauth_token['access_token'] = oauth_token['token']
+          oauth_token.delete('token')
+        end
+        oauth_token = OAuth2::AccessToken.from_hash(client, oauth_token)
       end
     end
+
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: whiplash-app
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Don Sullivan, Mark Dickson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-07-17 00:00:00.000000000 Z
+date: 2017-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oauth2
@@ -138,10 +138,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
 summary: this gem provides connectivity to the Whiplash API for authentication and
   REST requests.
 test_files: []
-has_rdoc: