whiplash-app 0.9.4 → 0.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 228da95848c936a8a771e6f67e6d4aa03899ab722274b2d355917593c9b83a89
-  data.tar.gz: 2f1f50222b2b7a578d23a88efdfd5328e2d0b772bdae0696249be13457e57db5
+  metadata.gz: ed3192117f026dce179a249afae7d1dd8e887883f4272ce9a8ceeff2f9ae9429
+  data.tar.gz: 2b3626ec34d6d3fe8bfd4111c3578235ae129321b090501cd0881917506aafe8
 SHA512:
-  metadata.gz: 31ba3a5b17e6679551d961ce009efb489e3a4a49bf0cf5cf8e9d4e978626c6ae825a38dad30d62552cf619e08a78a09066cd3ffb67a04599f5dcb6f7d01bc4a4
-  data.tar.gz: e845ad83845b36f932d21a3fd4fa283e8ef0fc45066cc37a82f80c3c178600a3c4870c76633f9ee88aad1967b16db7e7caf280a55e91b2f0d0d7fcf4ce6965e1
+  metadata.gz: 8a2ad62e4666d538fed3ecefb03bd675196c4c2612255f84e38e5865d5abca52a2bbe1c026b6e52cc14c16a9c409719c4cd404f60d7d0cbbfdc0e477232ae8c2
+  data.tar.gz: cee2a29068bf4ca7e200085539738a902c72c096bc01af699cb8a2330e1c2511a86715fc4d2aefd15487d603f31d0011972cdf1bd6ddefc2678b0a6ec5560db5

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,76 @@ 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, "customer_ids":[1, 2, 3]},
+    "customer": {"id": 123, "name": "BooYaa"},
+    "warehouse": {"id": 1, "name": "Ann Arbor"}
+}
 ```
 
-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'
+`current_customer` - This is a **hash** with the above fields; you typically shouldn't need much more user info than this
+`current_warehouse` - 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 `locale`.
+`set_current_customer_cookie!` - Updates the current customer cookie with fresh data from the api; typically used after you've changed customer
+`set_current_warehouse_cookie!` - Updates the current customer cookie with fresh data from the api; typically used after you've changed warehouse
+`unset_current_customer_cookie!` - Deletes the current customer cookie, with appropriate domain settings
+`unset_current_warehouse_cookie!` - Deletes the current warehouse cookie, with appropriate domain settings
+`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 +102,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 +143,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/controller_helpers.rb

@@ -8,7 +8,9 @@ module Whiplash
         helper_method :cookie_domain,
                       :core_url,
                       :core_url_for,
-                      :current_user
+                      :current_customer,
+                      :current_user,
+                      :current_warehouse
       end 
 
       private
@@ -25,6 +27,28 @@ module Whiplash
         [core_url, path].join('/')
       end
 
+      def current_customer
+        return if cookies[:customer].blank?
+        begin
+          customer_hash = JSON.parse(cookies[:customer])
+          @current_customer ||= customer_hash
+        rescue StandardError => e 
+          Rails.logger.warn "Customer could not be initialized: #{e.message}"
+          nil
+        end
+      end
+
+      def current_customer_full
+        return if cookies[:customer].blank?
+        begin
+          customer_hash = JSON.parse(cookies[:customer])
+          @current_customer ||= @whiplash_api.get!("customers/#{customer_hash['id']}").body
+        rescue StandardError => e 
+          Rails.logger.warn "Customer could not be initialized: #{e.message}"
+          nil
+        end
+      end
+
       def current_user
         return if cookies[:user].blank?
         begin
@@ -35,6 +59,28 @@ module Whiplash
         end
       end
 
+      def current_warehouse
+        return if cookies[:warehouse].blank?
+        begin
+          warehouse_hash = JSON.parse(cookies[:warehouse])
+          @current_warehouse ||= warehouse_hash
+        rescue StandardError => e 
+          Rails.logger.warn "Warehouse could not be initialized: #{e.message}"
+          @current_warehouse = nil
+        end
+      end
+
+      def current_warehouse_full
+        return if cookies[:warehouse].blank?
+        begin
+          warehouse_hash = JSON.parse(cookies[:warehouse])
+          @whiplash_api.get!("warehouses/#{warehouse_hash['id']}").body
+        rescue StandardError => e 
+          Rails.logger.warn "Warehouse could not be initialized: #{e.message}"
+          nil
+        end
+      end
+
       def http_scheme
         URI(core_url).scheme
       end
@@ -59,10 +105,25 @@ module Whiplash
         I18n.locale = current_user.try('locale') || I18n.default_locale
       end
 
+      def set_current_customer_cookie!(customer_id, expires_at = nil)
+        customer = @whiplash_api.get!("customers/#{customer_id}").body
+        user = @whiplash_api.get!("me").body
+        fields_we_care_about = %w(id name)
+        customer_hash = customer.slice(*fields_we_care_about)
+        expires_at ||= user['current_sign_in_expires_at']
+
+        shared_values = {
+          expires: DateTime.parse(expires_at),
+          secure: http_scheme == 'https',
+          samesite: :strict,
+          domain: cookie_domain
+        }
+        cookies[:customer] = shared_values.merge(value: customer_hash.to_json)
+      end
 
       def set_current_user_cookie!(expires_at = nil)
         user = @whiplash_api.get!("me").body
-        fields_we_care_about = %w(id email role locale first_name last_name partner_id warehouse_id customer_ids)
+        fields_we_care_about = %w(id email role locale first_name last_name partner_id customer_ids)
         user_hash = user.slice(*fields_we_care_about)
         expires_at ||= user['current_sign_in_expires_at']
 
@@ -75,6 +136,30 @@ module Whiplash
         cookies[:user] = shared_values.merge(value: user_hash.to_json)
       end
 
+      def set_current_warehouse_cookie!(warehouse_id, expires_at = nil)
+        warehouse = @whiplash_api.get!("warehouses/#{warehouse_id}").body
+        user = @whiplash_api.get!("me").body
+        fields_we_care_about = %w(id name)
+        warehouse_hash = warehouse.slice(*fields_we_care_about)
+        expires_at ||= user['current_sign_in_expires_at']
+
+        shared_values = {
+          expires: DateTime.parse(expires_at),
+          secure: http_scheme == 'https',
+          samesite: :strict,
+          domain: cookie_domain
+        }
+        cookies[:warehouse] = shared_values.merge(value: warehouse_hash.to_json)
+      end
+
+      def unset_current_customer_cookie!
+        cookies.delete(:customer, domain: cookie_domain)
+      end
+
+      def unset_current_warehouse_cookie!
+        cookies.delete(:warehouse, domain: cookie_domain)
+      end
+
     end
   end
 end

data/lib/whiplash/app/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: whiplash-app
 version: !ruby/object:Gem::Version
-  version: 0.9.4
+  version: 0.9.6
 platform: ruby
 authors:
 - Don Sullivan, Mark Dickson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-01-10 00:00:00.000000000 Z
+date: 2024-01-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oauth2