effective_qb_online 0.9.10 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6a3e221e9f86bab6fec4bbdf698d486a12924850960c797e897a79a9dde137e
-  data.tar.gz: eceb1df9ab98fd686e43e23572ef6be5ace97720bddaf35df4878dee8c5fafbe
+  metadata.gz: 78a04b8a3964143fa09e0cae9d54c29619a9b55d8f28b8079bb0b9c900301199
+  data.tar.gz: 9e52ef89f8402f6648b21063804deb9b9a8818facf74f877c0bff40992a3ab15
 SHA512:
-  metadata.gz: 481a68ddeda1c7dd2fc07f6c5a44758df77f7bed84a84313f8f33850c3b061a59444c5f3f9654e35f114677752e12b750909f0fb45e5298a8d6a7282e59a19ab
-  data.tar.gz: 6840d8757d7d237283957334a868f447348395972f42e09c036bd6b6f16ac6e7baf5b84dea43419d9653e2e9968527c8dfba2a10424ee4d41f87978c1800fa2c
+  metadata.gz: 633be21ff66eecb59f7fbc422145f163e311ed65e9e16ed8b9b215e40fdf278c6b6449bd72cfee7172d0d2f967aac871f8ffdbae1332652cd1a14dff9152a493
+  data.tar.gz: '0843e178990e9c31a99e6d4d2b4875fdd0a202bfffcf4240c7e7fbd05e711513c1301739611bf4ad0de26a30f2b1603c92d68c97e29733cfa510e3c7d835641a'

data/app/controllers/effective/qb_oauth_controller.rb

@@ -10,10 +10,11 @@ module Effective
     before_action { EffectiveResources.authorize!(self, :admin, :effective_qb_online) }
 
     def authorize
+      session[:qb_oauth_state] = SecureRandom.hex(24)
       grant_url = client.auth_code.authorize_url(
         redirect_uri: redirect_uri,
         response_type: 'code',
-        state: SecureRandom.hex(12),
+        state: session[:qb_oauth_state],
         scope: 'com.intuit.quickbooks.accounting'
       )
 
@@ -22,44 +23,77 @@ module Effective
 
     # This matches the QuickBooks Redirect URI and we have to set it up ahead of time.
     def callback
-      return unless params[:code].present? && params[:realmId].present? && params[:state].present?
+      expected_state = session.delete(:qb_oauth_state)
+      unless expected_state.present? && params[:state].present? && ActiveSupport::SecurityUtils.secure_compare(expected_state, params[:state].to_s)
+        flash[:danger] = 'Invalid QuickBooks authorization response. Please start the connection again.'
+        return redirect_to(effective_qb_online.admin_quickbooks_path)
+      end
 
-      token = client.auth_code.get_token(params[:code], redirect_uri: redirect_uri)
-      return unless token
+      unless params[:code].present? && params[:realmId].present?
+        flash[:danger] = 'QuickBooks authorization was not completed. Please try again.'
+        return redirect_to(effective_qb_online.admin_quickbooks_path)
+      end
 
       realm = Effective::QbRealm.all.first_or_initialize
+      if realm.persisted? && realm.realm_id != params[:realmId].to_s
+        flash[:danger] = 'Please reconnect the existing QuickBooks company. Selecting another company would invalidate your account settings and receipt history.'
+        return redirect_to(effective_qb_online.admin_quickbooks_path)
+      end
 
-      realm.update!(
-        realm_id: params[:realmId],
-        access_token: token.token,
-        refresh_token: token.refresh_token,
-        access_token_expires_at: Time.at(token.expires_at),
-        refresh_token_expires_at: (Time.at(token.expires_at) + 100.days)
-      )
+      token = client.auth_code.get_token(params[:code], redirect_uri: redirect_uri)
+
+      realm.with_lock do
+        realm.update!(
+          realm_id: params[:realmId],
+          access_token: token.token,
+          refresh_token: token.refresh_token,
+          access_token_expires_at: Time.at(token.expires_at),
+          refresh_token_expires_at: Time.current + token.params.fetch('x_refresh_token_expires_in', 100.days).to_i.seconds,
+          reconnection_required_at: nil,
+          reconnection_reason: nil
+        )
+      end
 
       flash[:success] = 'Successfully connected with QuickBooks Online'
 
       redirect_to(effective_qb_online.admin_quickbooks_path, allow_other_host: true)
+    rescue OAuth2::Error, Faraday::Error, ActiveRecord::RecordNotFound
+      flash[:danger] = 'QuickBooks authorization could not be completed. Please start the connection again.'
+      redirect_to(effective_qb_online.admin_quickbooks_path)
     end
 
     def revoke
-      realm = EffectiveQbOnline.api.realm
-      return unless realm
-
-      # Instantiate the token
-      token = OAuth2::AccessToken.new(client, realm.access_token, refresh_token: realm.refresh_token)
+      realm = Effective::QbRealm.first
 
-      # Revoke
-      response = token.post('/o/oauth2/revoke', params: { token: realm.refresh_token })
-
-      if response.status == 200
-        flash[:success] = 'Successfully revoked from QuickBooks Online'
-        realm.destroy!
+      if realm.blank?
+        flash[:success] = 'Already disconnected from QuickBooks Online'
       else
-        flash[:danger] = 'Unable to revoke'
+        revoked_refresh_token = realm.refresh_token
+        unless EffectiveQbOnline.revoke_token!(realm)
+          flash[:danger] = 'Unable to revoke QuickBooks access. Please try again or reconnect using a current company administrator.'
+          return redirect_to(effective_qb_online.admin_quickbooks_path)
+        end
+
+        realm.with_lock do
+          if realm.refresh_token == revoked_refresh_token
+            realm.destroy!
+            flash[:success] = 'Successfully revoked from QuickBooks Online'
+          else
+            flash[:danger] = 'The QuickBooks connection changed while revoking access. Your newer connection has been preserved.'
+          end
+        end
       end
 
-      redirect_to(effective_qb_online.admin_quickbooks_path, allow_other_host: true)
+      redirect_to(effective_qb_online.admin_quickbooks_path)
+    rescue ActiveRecord::RecordNotFound
+      flash[:success] = 'Already disconnected from QuickBooks Online'
+      redirect_to(effective_qb_online.admin_quickbooks_path)
+    rescue OAuth2::Error
+      flash[:danger] = 'QuickBooks could not revoke access. Your connection settings have been preserved. Please reconnect or try again.'
+      redirect_to(effective_qb_online.admin_quickbooks_path)
+    rescue Faraday::Error
+      flash[:danger] = 'Unable to reach QuickBooks Online. Please try again.'
+      redirect_to(effective_qb_online.admin_quickbooks_path)
     end
 
     private

data/app/mailers/effective/qb_online_mailer.rb

@@ -2,6 +2,16 @@ module Effective
   class QbOnlineMailer < EffectiveQbOnline.parent_mailer_class
     include EffectiveMailer
 
+    def reconnection_required(resource, opts = {})
+      raise('expected an Effective::QbRealm') unless resource.kind_of?(Effective::QbRealm)
+      @qb_realm = resource
+
+      to = EffectiveOrders.qb_online_sync_error_recipients.presence || EffectiveOrders.mailer_admin
+      cc = EffectiveQbOnline.sync_error_cc_recipients.presence
+      subject = subject_for(__method__, 'QuickBooks Online reconnection required', resource, opts)
+      mail(to: to, cc: cc, subject: subject, **headers_for(resource, opts))
+    end
+
     def sync_error(resource, opts = {})
       raise('expected an Effective::QbReceipt') unless resource.kind_of?(Effective::QbReceipt)
 

data/app/models/effective/qb_api.rb

@@ -223,31 +223,61 @@ module Effective
       end
     end
 
-    def with_authenticated_request(max_attempts: 3, &block)
+    def with_authenticated_request(max_attempts: 2)
       attempts = 0
 
       begin
+        realm.reload
+        if realm.reconnection_required?
+          raise EffectiveQbOnline::ReconnectionRequired, 'QuickBooks Online requires reconnection by a current company administrator. Retry this receipt manually after reconnecting.'
+        end
+
+        if @access_token && (@access_token.token != realm.access_token || @access_token.refresh_token != realm.refresh_token)
+          @access_token = nil
+        end
+
         @access_token ||= OAuth2::AccessToken.new(EffectiveQbOnline.oauth2_client, realm.access_token, refresh_token: realm.refresh_token)
         yield(@access_token)
-      rescue OAuth2::Error, Quickbooks::AuthorizationFailure => e
-        puts "QuickBooks OAuth Error: #{e.message}"
+      rescue OAuth2::Error, Quickbooks::AuthorizationFailure => error
+        # Only authentication failures justify refreshing. Other OAuth/API errors
+        # retain their original meaning and must not cause a token rotation.
+        raise unless error.kind_of?(Quickbooks::AuthorizationFailure) || error.response.status == 401
 
         attempts += 1
-        raise "unable to refresh QuickBooks OAuth2 token" if attempts >= max_attempts
+        raise if attempts >= max_attempts
 
-        # Refresh
-        refreshed = @access_token.refresh!
-        @access_token = nil  # Clear memoized token so it's rebuilt with new credentials
+        refresh_access_token!
+        retry
+      end
+    end
 
+    def refresh_access_token!
+      attempted_refresh_token = @access_token.refresh_token
+
+      # Refresh tokens rotate. Reload under a lock so another worker's successful
+      # refresh is reused instead of overwritten with stale credentials.
+      realm.with_lock do
+        return if realm.reconnection_required?
+        return if realm.access_token != @access_token.token || realm.refresh_token != attempted_refresh_token
+
+        refreshed = @access_token.refresh!
         realm.update!(
           access_token: refreshed.token,
           refresh_token: refreshed.refresh_token,
           access_token_expires_at: Time.at(refreshed.expires_at),
-          refresh_token_expires_at: (Time.at(refreshed.expires_at) + 100.days)
+          refresh_token_expires_at: Time.current + refreshed.params.fetch('x_refresh_token_expires_in', 100.days).to_i.seconds
         )
-
-        retry
       end
+    rescue OAuth2::Error => error
+      raise unless error.code == 'invalid_grant'
+
+      reason = error.response.parsed['x_error_reason'].presence || 'invalid_grant'
+      realm.require_reconnection!(reason: reason, refresh_token: attempted_refresh_token)
+      return unless realm.reconnection_required?
+
+      raise EffectiveQbOnline::ReconnectionRequired, 'QuickBooks Online authorization is no longer valid. Reconnect using a current company administrator, then retry errored receipts manually.'
+    ensure
+      @access_token = nil
     end
 
     def scrub(value, sql: false)

data/app/models/effective/qb_realm.rb

@@ -18,6 +18,9 @@ module Effective
       payment_method_id                   :string
       order_number_as_transaction_number  :boolean, default: false
 
+      reconnection_required_at            :datetime
+      reconnection_reason                 :string
+
       timestamps
     end
 
@@ -34,6 +37,26 @@ module Effective
       'QuickBooks Online Settings'
     end
 
+    def reconnection_required?
+      reconnection_required_at.present?
+    end
+
+    # Only the first failure for the current grant sends a notification. A failed
+    # request using old credentials must not disable a newly reconnected grant.
+    def require_reconnection!(reason:, refresh_token:)
+      changed = false
+
+      with_lock do
+        if !reconnection_required? && self.refresh_token == refresh_token
+          update!(reconnection_required_at: Time.current, reconnection_reason: reason)
+          changed = true
+        end
+      end
+
+      EffectiveQbOnline.send_email(:reconnection_required, self) if changed
+      changed
+    end
+
     def configured?
       realm_id.present? && access_token.present? && deposit_to_account_id.present? && payment_method_id.present?
     end

data/app/models/effective/qb_receipt.rb

@@ -96,7 +96,7 @@ module Effective
       rescue => e
         result = [e.message, ("(intuit_tid: #{e.intuit_tid})" if e.try(:intuit_tid).present?)].compact.join("\n\n")
         assign_attributes(result: result)
-        error!
+        error!(notify: !e.kind_of?(EffectiveQbOnline::ReconnectionRequired))
       end
 
     end
@@ -110,10 +110,10 @@ module Effective
       completed!
     end
 
-    def error!
+    def error!(notify: true)
       errored!
       EffectiveLogger.error(result, associated: self) if defined?(EffectiveLogger)
-      EffectiveQbOnline.send_email(:sync_error, self) if EffectiveOrders.send_qb_online_sync_error
+      EffectiveQbOnline.send_email(:sync_error, self) if notify && EffectiveOrders.send_qb_online_sync_error
 
       false
     end

data/app/models/effective/qb_sales_receipt.rb

@@ -165,13 +165,14 @@ module Effective
     end
 
     # Order item names may contain HTML (e.g. an EventRegistrant's "Member" badge).
-    # QuickBooks line item descriptions are plain text, so strip the markup while keeping
-    # the badge text. Convert line breaks to spaces first so adjacent text doesn't run together.
+    # QuickBooks line item descriptions are plain text, so strip the markup while keeping the badge text.
+    # <br> and &nbsp; carry spacing, so they become spaces rather than being dropped or passed through.
+    # The sanitizer re-encodes as it strips, so unescape after or a title with an & syncs as &amp;
     def self.strip_html(value)
       return value if value.blank?
 
-      text = value.to_s.gsub(/<br\s*\/?>/i, ' ')
-      ActionView::Base.full_sanitizer.sanitize(text).squish
+      text = ActionView::Base.full_sanitizer.sanitize(value.to_s.gsub(/<br\s*\/?>/i, ' '))
+      CGI.unescapeHTML(text.gsub('&nbsp;', ' ')).squish
     end
 
   end

data/app/views/admin/qb_online/_company.html.haml

@@ -1,4 +1,11 @@
-- company_info = (api.company_info rescue nil)
+- company_info = (api.company_info rescue nil) unless api.realm.reconnection_required? || local_assigns[:api_error].present?
+
+- if api.realm.reconnection_required?
+  .alert.alert-warning
+    %p QuickBooks Online authorization is no longer valid. Reconnect using a current company administrator.
+    %p Your company settings and receipts have been preserved. After reconnecting, retry errored receipts manually.
+    = link_to 'Reconnect QuickBooks', effective_qb_online.quickbooks_oauth_path, class: 'btn btn-primary'
+
 
 - if company_info.present?
   %table.table.table-sm
@@ -50,7 +57,7 @@
     %tbody
       %tr
         %td QuickBooks API Error
-        %td= api.api_error
+        %td= api.realm.reconnection_required? ? 'Reconnection required' : (local_assigns[:api_error] || api.api_error)
 
       %tr
         %td QuickBooks Online

data/app/views/admin/qb_online/index.html.haml

@@ -1,6 +1,7 @@
 %h1.effective-admin-heading= @page_title
 
 - api = EffectiveQbOnline.api
+- api_error = api.api_error if api.present? && !api.realm.reconnection_required?
 
 - if api.blank?
   = card('Connect to QuickBooks Online') do
@@ -11,13 +12,13 @@
     = card('Test Credentials') do
       = render('test_credentials', api: api)
 
-  - if api.realm&.configured?
+  - if api.realm&.configured? && !api.realm.reconnection_required?
     .mb-2
       = collapse('Show Company Settings') do
-        = render('company', api: api)
+        = render('company', api: api, api_error: api_error)
   - else
     = card('Company') do
-      = render('company', api: api)
+      = render('company', api: api, api_error: api_error)
 
   = card('Sales Receipts') do
     .text-right.mb-2

data/app/views/effective/qb_online_mailer/reconnection_required.html.haml

@@ -0,0 +1,7 @@
+%p QuickBooks Online authorization is no longer valid for company #{@qb_realm.realm_id}.
+%p Sign in as a website administrator and reconnect using a current QuickBooks company administrator.
+%p Background QuickBooks requests are paused until reconnection. Company settings and receipts have been preserved.
+%p After reconnecting, review errored receipts and retry them manually.
+%p= link_to 'Reconnect QuickBooks Online', effective_qb_online.admin_quickbooks_url
+
+%p Have a great day!

data/db/migrate/101_create_effective_qb_online.rb

@@ -14,6 +14,9 @@ class CreateEffectiveQbOnline < ActiveRecord::Migration[6.0]
 
       t.boolean :order_number_as_transaction_number, default: false
 
+      t.datetime :reconnection_required_at
+      t.string :reconnection_reason
+
       t.timestamps
     end
 

data/db/migrate/20261013140000_upgrade_effective_qb_online_zero_nine_twelve.rb

@@ -0,0 +1,11 @@
+class UpgradeEffectiveQbOnlineZeroNineTwelve < ActiveRecord::Migration[6.0]
+  def up
+    add_column :qb_realms, :reconnection_required_at, :datetime unless column_exists?(:qb_realms, :reconnection_required_at)
+    add_column :qb_realms, :reconnection_reason, :string unless column_exists?(:qb_realms, :reconnection_reason)
+  end
+
+  def down
+    remove_column :qb_realms, :reconnection_reason if column_exists?(:qb_realms, :reconnection_reason)
+    remove_column :qb_realms, :reconnection_required_at if column_exists?(:qb_realms, :reconnection_required_at)
+  end
+end

data/lib/effective_qb_online/version.rb

@@ -1,3 +1,3 @@
 module EffectiveQbOnline
-  VERSION = '0.9.10'.freeze
+  VERSION = '0.10.0'.freeze
 end

data/lib/effective_qb_online.rb

@@ -21,19 +21,35 @@ module EffectiveQbOnline
     mailer&.constantize || Effective::QbOnlineMailer
   end
 
+  class ReconnectionRequired < StandardError; end
+
   def self.oauth2_client
-    @oauth2_client ||= OAuth2::Client.new(
+    OAuth2::Client.new(
       oauth_client_id,
       oauth_client_secret,
       site: 'https://appcenter.intuit.com/connect/oauth2',
       authorize_url: 'https://appcenter.intuit.com/connect/oauth2',
       token_url: 'https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer',
+      revoke_url: 'https://developer.api.intuit.com/v2/oauth2/tokens/revoke',
       connection_opts: {
         request: { open_timeout: 10, timeout: 30 }
       }
     )
   end
 
+  # Intuit requires client authentication rather than an access-token bearer header.
+  # https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0
+  def self.revoke_token!(realm)
+    response = oauth2_client.revoke_token(
+      realm.refresh_token,
+      nil,
+      token_method: :post,
+      headers: { 'Content-Type' => 'application/json', 'Accept' => 'application/json' }
+    )
+
+    response.status == 200
+  end
+
   def self.api(realm: nil)
     realm ||= Effective::QbRealm.first
     return nil if realm.blank?

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: effective_qb_online
 version: !ruby/object:Gem::Version
-  version: 0.9.10
+  version: 0.10.0
 platform: ruby
 authors:
 - Code and Effect
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-20 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -28,30 +27,82 @@ dependencies:
   name: quickbooks-ruby
   requirement: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.0.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.0.7
+- !ruby/object:Gem::Dependency
+  name: oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.25
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.25
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.14.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.14.4
 - !ruby/object:Gem::Dependency
   name: faraday-net_http_persistent
   requirement: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.3.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.3.1
 - !ruby/object:Gem::Dependency
   name: effective_bootstrap
   requirement: !ruby/object:Gem::Requirement
@@ -258,10 +309,12 @@ files:
 - app/views/admin/qb_receipts/_form.html.haml
 - app/views/admin/qb_receipts/edit.html.haml
 - app/views/admin/qb_receipts/new.html.haml
+- app/views/effective/qb_online_mailer/reconnection_required.html.haml
 - app/views/effective/qb_online_mailer/sync_error.html.haml
 - config/effective_qb_online.rb
 - config/routes.rb
 - db/migrate/101_create_effective_qb_online.rb
+- db/migrate/20261013140000_upgrade_effective_qb_online_zero_nine_twelve.rb
 - db/seeds.rb
 - lib/effective_qb_online.rb
 - lib/effective_qb_online/engine.rb
@@ -273,7 +326,6 @@ homepage: https://github.com/code-and-effect/effective_qb_online
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -288,8 +340,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
-signing_key:
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Create QuickBooks Online SalesReceipts for purchased effective orders
 test_files: []