whiplash-app 0.9.4 → 0.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 228da95848c936a8a771e6f67e6d4aa03899ab722274b2d355917593c9b83a89
-  data.tar.gz: 2f1f50222b2b7a578d23a88efdfd5328e2d0b772bdae0696249be13457e57db5
+  metadata.gz: e0e2ae334bdd40de1ae96543cd86eb7506e3de9a7d65d04b003fa67d2eb83da1
+  data.tar.gz: a2ae0fe3f75c4ed25e7703c85f71495609f10434c9bf3d687483d1ad440a5513
 SHA512:
-  metadata.gz: 31ba3a5b17e6679551d961ce009efb489e3a4a49bf0cf5cf8e9d4e978626c6ae825a38dad30d62552cf619e08a78a09066cd3ffb67a04599f5dcb6f7d01bc4a4
-  data.tar.gz: e845ad83845b36f932d21a3fd4fa283e8ef0fc45066cc37a82f80c3c178600a3c4870c76633f9ee88aad1967b16db7e7caf280a55e91b2f0d0d7fcf4ce6965e1
+  metadata.gz: 1fd9e63cc8d1359a38adc462eb4818928d4ea84bc1e57db46e1fa9725ef547c59172763727f8fc7957c8de22d0a3720a437040789966116ce5a1c0a833ad210f
+  data.tar.gz: 0f35b12647a50d4a4c8fbb1a0f24fb6d40946c19dbbeb4d0238eb19d5c075fd3958e2cea68a72072d8db5770c83d18a5c1bc831a3bee2497e9cc7a4bfde52913

data/README.md

@@ -4,6 +4,8 @@ The whiplash-app gem allows your Whiplash application to access the Whiplash
 API and perform authentication, signatures and signature verification, and basic
 CRUD functions against the api.
 
+For apps that provide a UI, it also provides built in authentication and several helper methods.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -22,109 +24,68 @@ Or install it yourself as:
 
 ## Usage
 
-**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
+There are two basic uses for this gem:
+1. Authenticating users for apps _with a UI_ (i.e. Notifications, Troubleshoot, etc)
+2. Providing offline access to applications that perform tasks (i.e Tasks, Old Integrations, etc)
 
-Before:
-```ruby
-api = Whiplash::App
-```
+It's not uncommon for an application to do _both_ of the above (i.e. Notifications, Payments, etc)
 
-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
+### Authentication for offline access (Oauth Client Credentials flow)
 In order to authenticate, make sure the following `ENV` vars are set:
 
 ```ruby
-ENV["WHIPLASH_CLIENT_ID"]
-ENV["WHIPLASH_CLIENT_SECRET"]
-ENV["WHIPLASH_CLIENT_SCOPE"]
+ENV['WHIPLASH_API_URL']
+ENV['WHIPLASH_CLIENT_ID']
+ENV['WHIPLASH_CLIENT_SCOPE']
+ENV['WHIPLASH_CLIENT_SECRET']
 ```
 
-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.
+Once those are set, you can generate and use an access token like so:
 
 ```ruby
-api = Whiplash::App.new
-api.refresh_token! # Since you don't have one yet
-api.token # Confirm you've got a token
+token = Whiplash::App.client_credentials_token
+api = Whiplash::App.new(token)
+customers = api.get!('customers')
 ```
 
-### 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.
+### Authentication for online access
+In order to use the API, you only need to set the following:
 
 ```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
+ENV['WHIPLASH_API_URL']
 ```
 
-### 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://sandbox.getwhiplash.com` (test or dev environment) or `https://www.getwhiplash.com` (prod environment).
+As long as all of your apps are on the same subdomain, they will share auth cookies:
 
-### 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
-
-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
-api.create(resource, params, headers)
+```json
+{
+    "oauth_token": XXXXXXX,
+    "user": {"id":151,"email":"mark@getwhiplash.com","role":"admin","locale":"en","first_name":"Mark","last_name":"Dickson","partner_id":null,"warehouse_id": 1,"customer_ids":[1, 2, 3]}
+}
 ```
 
-For member actions, such as `show`, or `destroy` methods, the pattern is this:
+You get a variety of helper methods for free:
 
-```ruby
-api.find(resource, id, headers)
-api.destroy(resource, id, headers)
-```
-
-Finally, for `update` calls, it's a mixture of those:
+`init_whiplash_api` - This instantiates `@whiplash_api` which can be used to make requests, out of the box
+`current_user` - This is a **hash** with the above fields; you typically shouldn't need much more user info than this
+`require_user` - Typically you'd use this in a `before_action`. You almost always want this in `ApplicationController`.
+`set_locale!` - Sets the locale based on the value in the user hash
+`set_current_user_cookie!` - Updates the current user cookie with fresh data from the api. You typically won't need this, unless your app updates fields like `warehouse_id` or `locale`.
+`core_url` - Shorthand for `ENV['WHIPLASH_API_URL']`
+`core_url_for` - Link back to Core like `core_url_for('login')`
 
-```ruby
-api.update(resource, id, params_to_update, headers)
-```
 
-So, basic AR style calls can be performed like so:
+### 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})`
 
-```ruby
-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
-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
 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
-api.get('orders/non_restful_action', {}, {})
 ```
 `POST`, `PUT`, and `DELETE` calls can be performed in much the same way:
 ```ruby
@@ -133,6 +94,37 @@ api.put(endpoint, params, headers) # PUT request to the specified endpoint passi
 api.delete(endpoint, params, headers) # DELETE request to the specified endpoint.  Params would probably just be an id.
 ```
 
+### Bang methods
+
+In typical Rails/Ruby fashion, `!` methods `raise`. Typically, you'll want to set some global `rescue`s and use the `!` version of crud requests:
+
+```ruby
+rescue_from WhiplashApiError, with: :handle_whiplash_api_error
+
+def handle_whiplash_api_error(exception)
+    # Any special exceptions we want to handle directly
+    case exception.class.to_s
+    when 'WhiplashApiError::Unauthorized'
+      return redirect_to core_url_for('logout')
+    end
+    
+    @status_code = WhiplashApiError.codes&.invert&.dig(exception&.class)
+    @error = exception.message
+    respond_to do |format|
+      format.html {
+        flash[:error] = @error
+        redirect_back(fallback_location: root_path)
+      }
+      format.json {
+        render json: exception, status: @status_code
+      }
+      format.js {
+        render template: 'resources/exception'
+      }
+    end
+end
+```
+
 ### Signing and Verifying.
 `whiplash-app` supports signing and verifying signatures like so:
 ```ruby
@@ -143,30 +135,6 @@ and verifications are done like so:
 Whiplash::App.verified?(request)
 ```  
 
-### 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"]
-ENV["REDIS_PASSWORD"]
-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/version.rb

@@ -1,5 +1,5 @@
 module Whiplash
   class App
-    VERSION = "0.9.4"
+    VERSION = "0.9.5"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: whiplash-app
 version: !ruby/object:Gem::Version
-  version: 0.9.4
+  version: 0.9.5
 platform: ruby
 authors:
 - Don Sullivan, Mark Dickson