whiplash-app 0.9.2 → 0.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90618c9787cb8660f4fcb0be146bdb14736ce8635274f9b262f68813268bd35d
-  data.tar.gz: a26cca38e01f5c5642b94afe39cbc0be6ea08f05c9ccf446d0d802e5548aa100
+  metadata.gz: e0e2ae334bdd40de1ae96543cd86eb7506e3de9a7d65d04b003fa67d2eb83da1
+  data.tar.gz: a2ae0fe3f75c4ed25e7703c85f71495609f10434c9bf3d687483d1ad440a5513
 SHA512:
-  metadata.gz: d67a3f4a633319407cb8dd9a6717a92b57480825dab3fa36b4e77fda280f58c16089aa833a39fade900dee77efeaa169b868e3ba5f0e25832e37105da40ad53b
-  data.tar.gz: 94df31ed65be70e565fb5ea8ba2744dbfbbfe386500d8ae5c57bce4bd72474ff0af70f4ea9620e02f2a108282d24821c6477b0107d0b55146249c690010f8d07
+  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/api_config.rb

@@ -10,6 +10,12 @@ module Whiplash
         end
       end
 
+      def rate_limit
+        (ENV['WHIPLASH_RATE_LIMIT'] || 25).to_i
+      end
+
+      private
+      
       def production_url
         ENV["WHIPLASH_API_URL"] || "https://www.getwhiplash.com"
       end
@@ -18,10 +24,6 @@ module Whiplash
         ENV["WHIPLASH_API_URL"] || "https://sandbox.getwhiplash.com"
       end
 
-      def rate_limit
-        (ENV['WHIPLASH_RATE_LIMIT'] || 25).to_i
-      end
-
     end
   end
 end

data/lib/whiplash/app/connections.rb

@@ -27,7 +27,7 @@ module Whiplash
 
       def app_request(options={})
         return base_app_request(options) unless defined?(Sidekiq)
-        limiter = Sidekiq::Limiter.window('whiplash-core', self.rate_limit, :second, wait_timeout: 15)
+        limiter = Sidekiq::Limiter.window('whiplash-core', self.class.rate_limit, :second, wait_timeout: 15)
         limiter.within_limit do
           base_app_request(options)
         end

data/lib/whiplash/app/controller_helpers.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+module Whiplash
+  class App
+    module ControllerHelpers
+      extend ActiveSupport::Concern
+
+      included do
+        helper_method :cookie_domain,
+                      :core_url,
+                      :core_url_for,
+                      :current_user
+      end 
+
+      private
+
+      def cookie_domain
+        '.' + URI.parse(core_url).host
+      end
+
+      def core_url
+        ENV['WHIPLASH_API_URL']
+      end
+
+      def core_url_for(path)
+        [core_url, path].join('/')
+      end
+
+      def current_user
+        return if cookies[:user].blank?
+        begin
+          @current_user ||= JSON.parse(cookies[:user])
+        rescue StandardError => e 
+          Rails.logger.warn "User could not be initialized: #{e.message}"
+          @current_user = nil
+        end
+      end
+
+      def http_scheme
+        URI(core_url).scheme
+      end
+
+      def init_whiplash_api(options = {})
+        return redirect_to core_url_for('login') if cookies[:oauth_token].blank?
+        token = {access_token: cookies[:oauth_token]}
+        begin 
+          @whiplash_api = Whiplash::App.new(token, options)
+        rescue StandardError => e 
+          Rails.logger.warn "API failed to initialize: #{e.message}"
+          @whiplash_api = nil
+        end
+      end
+    
+      def require_user
+        redirect_to core_url_for('login') if current_user.blank?
+      end
+    
+      def set_locale!
+        I18n.default_locale = :en
+        I18n.locale = current_user.try('locale') || I18n.default_locale
+      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)
+        user_hash = user.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[:user] = shared_values.merge(value: user_hash.to_json)
+      end
+
+    end
+  end
+end

data/lib/whiplash/app/railtie.rb

@@ -1,14 +1,31 @@
 # frozen_string_literal: true
 
 module Whiplash
-  module Logs
+  class App
     class Railtie < Rails::Railtie
+
+      config.before_configuration do |app|
+        # App name/etc, mainly for consistency in logging
+        app_name = app.class.module_parent.name.underscore.dasherize
+        app.config.environment_key = ENV.fetch('ENVIRONMENT_KEY', Rails.env.to_s)
+        app.config.application_key = ENV.fetch('APPLICATION_KEY', app_name)
+        app.config.application_name_space = [config.application_key, config.environment_key].join('-')
+    
+        # session settings
+        session_days = 30 
+        session_seconds = session_days * 24 * 60 * 60
+        session_length = ENV.fetch('SESSION_LENGTH', session_seconds).to_i
+        app.config.session_length = session_length
+        app.config.session_store :cookie_store, :key => '_session', :expire_after => session_length
+      end
+
       initializer "whiplash_app.action_controller" do
         ActiveSupport.on_load(:action_controller) do
-          puts "Extending #{self} with YourGemsModuleName::Controller"
           include Whiplash::App::CanonicalHost
+          include Whiplash::App::ControllerHelpers
         end
       end
+
     end
   end
 end

data/lib/whiplash/app/version.rb

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

data/lib/whiplash/app.rb

@@ -9,16 +9,17 @@ require "faraday"
 
 # Rails app stuff
 if defined?(Rails::Railtie)
-  require "whiplash/app/canonical_host" 
   require "whiplash/app/railtie"
+  require "whiplash/app/canonical_host" 
+  require "whiplash/app/controller_helpers"
 end 
 
 module Whiplash
   class App
-    include Whiplash::App::ApiConfig
+    extend Whiplash::App::Signing
+    extend Whiplash::App::ApiConfig
     include Whiplash::App::Connections
     include Whiplash::App::FinderMethods
-    extend Whiplash::App::Signing
 
     attr_accessor :customer_id, :shop_id, :token
 
@@ -29,16 +30,16 @@ module Whiplash
       @api_version = options[:api_version] || 2 # can be 2_1
     end
 
-    def client
-      OAuth2::Client.new(ENV["WHIPLASH_CLIENT_ID"], ENV["WHIPLASH_CLIENT_SECRET"], site: api_url)
-    end
-
     def versioned_api_url
       "api/v#{@api_version}"
     end
 
+    def client
+      OAuth2::Client.new(ENV["WHIPLASH_CLIENT_ID"], ENV["WHIPLASH_CLIENT_SECRET"], site: self.class.api_url)
+    end
+
     def connection
-      Faraday.new [api_url, versioned_api_url].join("/") do |conn|
+      Faraday.new [self.class.api_url, versioned_api_url].join("/") do |conn|
         conn.request :authorization, 'Bearer', token.token
         conn.request :json
         conn.response :json, :content_type => /\bjson$/
@@ -53,9 +54,9 @@ module Whiplash
       case ENV["WHIPLASH_CLIENT_SCOPE"]
       when /app_(manage|read)/
         begin
-          access_token = client.client_credentials.get_token(scope: ENV["WHIPLASH_CLIENT_SCOPE"])
+          access_token = self.class.client_credentials_token
         rescue URI::InvalidURIError => e
-          raise StandardError, "The provide URL (#{ENV["WHIPLASH_API_URL"]}) is not valid"
+          raise StandardError, "The provided URL (#{ENV["WHIPLASH_API_URL"]}) is not valid"
         end
       else
         raise StandardError, "You must request an access token before you can refresh it" if token.nil?
@@ -70,6 +71,13 @@ module Whiplash
       false
     end
 
+    class << self 
+      def client_credentials_token
+        client = OAuth2::Client.new(ENV["WHIPLASH_CLIENT_ID"], ENV["WHIPLASH_CLIENT_SECRET"], site: api_url)
+        client.client_credentials.get_token(scope: ENV["WHIPLASH_CLIENT_SCOPE"])
+      end
+    end
+
     private
     def format_token(oauth_token)
       return oauth_token if oauth_token.is_a?(OAuth2::AccessToken)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: whiplash-app
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.9.5
 platform: ruby
 authors:
 - Don Sullivan, Mark Dickson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-12-20 00:00:00.000000000 Z
+date: 2024-01-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oauth2
@@ -117,6 +117,7 @@ files:
 - lib/whiplash/app/api_config.rb
 - lib/whiplash/app/canonical_host.rb
 - lib/whiplash/app/connections.rb
+- lib/whiplash/app/controller_helpers.rb
 - lib/whiplash/app/finder_methods.rb
 - lib/whiplash/app/railtie.rb
 - lib/whiplash/app/signing.rb