omniauth-quickbooks-oauth2-modern 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be89aee453817eeae8a1010d880f1e3573dc56355347c29211f4b2b535e25c4d
-  data.tar.gz: 217a086f82719d772996ab2c267f5015718abb6522f4e0daf28a31a50b07e5eb
+  metadata.gz: b34af49e6a0c3fb18416a2f2375d4de6fbc9a8db55277776320c9b21aa0e44f3
+  data.tar.gz: 2cd785029a2b9a26fc7f3bdfe8fc5b716d6aeafab47e1ffeb297d7b0b837a1c7
 SHA512:
-  metadata.gz: 3b866eb508a50c13f73ab54fafaddc423caf683cc44c272c41c4283300e627c8c29be457b89e49c1ba09916c48681db94705fbdd34212e57f0a70a0117d32b73
-  data.tar.gz: 0f880dcb6684f6d2818b3be82c44b3dbd097a26ccf5460238ca10b40b6cb2fc3e7305d7ea663db7262eb43333e4f356cb5f2886ddc035f6f3d82b42187401c46
+  metadata.gz: d411ec48a52dc0fb5f064273778025676637aab84e8c008d1127b342c5a60f834f539548cbaf955027bc7a2df7457dea6839f51799ee65611046c3eac9f77094
+  data.tar.gz: '09794199b6e906a18fd2091437262e1ea1a903ccced8347271bed6adb719f1925b43940c335fc1246a96ba85f674072450a7608f6a6d02e34c12690aa041d098'

data/.rubocop.yml

@@ -1,9 +1,11 @@
+require:
+  - rubocop-rspec
+
 AllCops:
   TargetRubyVersion: 3.0
   NewCops: enable
   Exclude:
     - "vendor/**/*"
-    - "spec/**/*"
 
 Style/Documentation:
   Enabled: false
@@ -12,3 +14,49 @@ Metrics/BlockLength:
   Exclude:
     - "spec/**/*"
     - "*.gemspec"
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+RSpec/SubjectStub:
+  Enabled: false
+
+RSpec/VerifiedDoubles:
+  Enabled: false
+
+RSpec/FilePath:
+  Enabled: false
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/ExampleLength:
+  Max: 15
+
+RSpec/NestedGroups:
+  Max: 5
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/DescribedClass:
+  Enabled: false
+
+Naming/FileName:
+  Exclude:
+    - 'lib/omniauth-quickbooks-oauth2-modern.rb'
+
+Metrics/ParameterLists:
+  Max: 8

data/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-01-31
+
+### Added
+
+- TokenClient class for easy token refresh in Rails apps
+- `refresh_token` method with result object pattern
+- `token_expired?` helper with configurable buffer
+- Comprehensive RSpec tests for TokenClient (26 new tests)
+
 ## [1.0.0] - 2026-01-31
 
 ### Added

data/README.md

@@ -201,6 +201,102 @@ def self.from_omniauth(auth)
 end
 ```
 
+## Token Refresh
+
+This gem includes a `TokenClient` class to easily refresh tokens in your Rails app.
+
+### Basic Usage
+
+```ruby
+# Create a client instance
+client = OmniAuth::QuickbooksOauth2Modern::TokenClient.new(
+  client_id: ENV['QBO_CLIENT_ID'],
+  client_secret: ENV['QBO_CLIENT_SECRET']
+)
+
+# Refresh an expired token
+result = client.refresh_token(account.qbo_refresh_token)
+
+if result.success?
+  account.update!(
+    qbo_access_token: result.access_token,
+    qbo_refresh_token: result.refresh_token,
+    qbo_token_expires_at: Time.at(result.expires_at)
+  )
+else
+  Rails.logger.error "Token refresh failed: #{result.error}"
+end
+```
+
+### Check Token Expiration
+
+```ruby
+# Check if token is expired (with 5-minute buffer by default)
+client.token_expired?(account.qbo_token_expires_at)
+
+# Custom buffer (e.g., refresh 1 hour before expiry)
+client.token_expired?(account.qbo_token_expires_at, buffer_seconds: 3600)
+```
+
+### Rails Service Example
+
+```ruby
+# app/services/quickbooks_api_service.rb
+class QuickBooksApiService
+  def initialize(account)
+    @account = account
+    @client = OmniAuth::QuickbooksOauth2Modern::TokenClient.new(
+      client_id: ENV['QBO_CLIENT_ID'],
+      client_secret: ENV['QBO_CLIENT_SECRET']
+    )
+  end
+
+  def with_valid_token
+    refresh_if_expired!
+    yield @account.qbo_access_token
+  end
+
+  private
+
+  def refresh_if_expired!
+    return unless @client.token_expired?(@account.qbo_token_expires_at)
+
+    result = @client.refresh_token(@account.qbo_refresh_token)
+    raise "Token refresh failed: #{result.error}" unless result.success?
+
+    @account.update!(
+      qbo_access_token: result.access_token,
+      qbo_refresh_token: result.refresh_token,
+      qbo_token_expires_at: Time.at(result.expires_at)
+    )
+  end
+end
+
+# Usage
+QuickBooksApiService.new(current_account).with_valid_token do |token|
+  # Make API calls with valid token
+  response = Faraday.get("https://quickbooks.api.intuit.com/v3/company/#{realm_id}/query") do |req|
+    req.headers['Authorization'] = "Bearer #{token}"
+    req.params['query'] = "SELECT * FROM Customer"
+  end
+end
+```
+
+### TokenResult Object
+
+The `refresh_token` method returns a `TokenResult` object with:
+
+| Method | Description |
+|--------|-------------|
+| `success?` | Returns `true` if refresh succeeded |
+| `failure?` | Returns `true` if refresh failed |
+| `access_token` | The new access token |
+| `refresh_token` | The new refresh token |
+| `expires_at` | Unix timestamp when token expires |
+| `expires_in` | Seconds until token expires |
+| `error` | Error message if failed |
+| `raw_response` | Full response hash from Intuit |
+
 ## Scopes
 
 Common QuickBooks scopes:

data/Rakefile

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
+require 'rubocop/rake_task'
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]

data/lib/omniauth/quickbooks_oauth2_modern/token_client.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require 'base64'
+
+module OmniAuth
+  module QuickbooksOauth2Modern
+    # Client for managing QuickBooks OAuth2 tokens
+    #
+    # This class provides an easy way to refresh expired tokens in your Rails app.
+    #
+    # @example Basic usage
+    #   client = OmniAuth::QuickbooksOauth2Modern::TokenClient.new(
+    #     client_id: ENV['QBO_CLIENT_ID'],
+    #     client_secret: ENV['QBO_CLIENT_SECRET']
+    #   )
+    #
+    #   # Refresh an expired token
+    #   result = client.refresh_token(user.qbo_refresh_token)
+    #   if result.success?
+    #     user.update!(
+    #       qbo_access_token: result.access_token,
+    #       qbo_refresh_token: result.refresh_token,
+    #       qbo_token_expires_at: result.expires_at
+    #     )
+    #   end
+    #
+    # @example With automatic token refresh in a service
+    #   class QuickBooksApiService
+    #     def initialize(account)
+    #       @account = account
+    #       @client = OmniAuth::QuickbooksOauth2Modern::TokenClient.new(
+    #         client_id: ENV['QBO_CLIENT_ID'],
+    #         client_secret: ENV['QBO_CLIENT_SECRET']
+    #       )
+    #     end
+    #
+    #     def with_valid_token
+    #       refresh_if_expired!
+    #       yield @account.access_token
+    #     end
+    #
+    #     private
+    #
+    #     def refresh_if_expired!
+    #       return unless @client.token_expired?(@account.token_expires_at)
+    #
+    #       result = @client.refresh_token(@account.refresh_token)
+    #       raise "Token refresh failed: #{result.error}" unless result.success?
+    #
+    #       @account.update!(
+    #         access_token: result.access_token,
+    #         refresh_token: result.refresh_token,
+    #         token_expires_at: result.expires_at
+    #       )
+    #     end
+    #   end
+    #
+    class TokenClient
+      # Result object for token operations
+      class TokenResult
+        attr_reader :access_token, :refresh_token, :expires_at, :expires_in, :error, :raw_response
+
+        def initialize(success:, access_token: nil, refresh_token: nil, expires_at: nil, expires_in: nil,
+                       error: nil, raw_response: nil)
+          @success = success
+          @access_token = access_token
+          @refresh_token = refresh_token
+          @expires_at = expires_at
+          @expires_in = expires_in
+          @error = error
+          @raw_response = raw_response
+        end
+
+        def success?
+          @success
+        end
+
+        def failure?
+          !@success
+        end
+      end
+
+      # Intuit OAuth2 token endpoint
+      TOKEN_URL = 'https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer'
+
+      attr_reader :client_id, :client_secret
+
+      # Initialize a new TokenClient
+      #
+      # @param client_id [String] Your QuickBooks App Client ID
+      # @param client_secret [String] Your QuickBooks App Client Secret
+      def initialize(client_id:, client_secret:)
+        @client_id = client_id
+        @client_secret = client_secret
+      end
+
+      # Refresh an access token using a refresh token
+      #
+      # @param refresh_token [String] The refresh token to use
+      # @return [TokenResult] Result object with new tokens or error
+      def refresh_token(refresh_token)
+        if refresh_token.nil? || refresh_token.empty?
+          return TokenResult.new(success: false,
+                                 error: 'Refresh token is required')
+        end
+
+        response = make_refresh_request(refresh_token)
+
+        if response.success?
+          parse_success_response(response)
+        else
+          parse_error_response(response)
+        end
+      rescue Faraday::Error => e
+        TokenResult.new(success: false, error: "Network error: #{e.message}")
+      rescue JSON::ParserError => e
+        TokenResult.new(success: false, error: "Invalid JSON response: #{e.message}")
+      rescue StandardError => e
+        TokenResult.new(success: false, error: "Unexpected error: #{e.message}")
+      end
+
+      # Check if a token is expired or about to expire
+      #
+      # @param expires_at [Time, Integer] Token expiration time
+      # @param buffer_seconds [Integer] Buffer before expiration (default: 300 = 5 minutes)
+      # @return [Boolean] True if token is expired or will expire within buffer
+      def token_expired?(expires_at, buffer_seconds: 300)
+        return true if expires_at.nil?
+
+        expires_at_time = expires_at.is_a?(Integer) ? Time.at(expires_at) : expires_at
+        Time.now >= (expires_at_time - buffer_seconds)
+      end
+
+      private
+
+      def make_refresh_request(refresh_token)
+        # QuickBooks uses Basic Auth with base64 encoded client_id:client_secret
+        credentials = Base64.strict_encode64("#{client_id}:#{client_secret}")
+
+        Faraday.post(TOKEN_URL) do |req|
+          req.headers['Authorization'] = "Basic #{credentials}"
+          req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
+          req.headers['Accept'] = 'application/json'
+          req.body = URI.encode_www_form(
+            grant_type: 'refresh_token',
+            refresh_token: refresh_token
+          )
+        end
+      end
+
+      def parse_success_response(response)
+        data = JSON.parse(response.body)
+
+        expires_in = data['expires_in']&.to_i
+        expires_at = expires_in ? Time.now.to_i + expires_in : nil
+
+        TokenResult.new(
+          success: true,
+          access_token: data['access_token'],
+          refresh_token: data['refresh_token'],
+          expires_in: expires_in,
+          expires_at: expires_at,
+          raw_response: data
+        )
+      end
+
+      def parse_error_response(response)
+        error_data = begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          { 'error' => response.body }
+        end
+
+        error_message = error_data['error_description'] || error_data['error'] || "HTTP #{response.status}"
+
+        TokenResult.new(
+          success: false,
+          error: error_message,
+          raw_response: error_data
+        )
+      end
+    end
+  end
+end

data/lib/omniauth/quickbooks_oauth2_modern/version.rb

@@ -2,6 +2,6 @@
 
 module OmniAuth
   module QuickbooksOauth2Modern
-    VERSION = "1.0.0"
+    VERSION = '1.1.0'
   end
 end

data/lib/omniauth/strategies/quickbooks_oauth2_modern.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require "omniauth-oauth2"
-require "faraday"
-require "json"
+require 'omniauth-oauth2'
+require 'faraday'
+require 'json'
 
 module OmniAuth
   module Strategies
@@ -24,15 +24,15 @@ module OmniAuth
       option :name, :quickbooks_oauth2_modern
 
       # Default scopes for QuickBooks accounting access with OpenID
-      option :scope, "com.intuit.quickbooks.accounting openid profile email"
+      option :scope, 'com.intuit.quickbooks.accounting openid profile email'
 
       # Sandbox mode (default: true for safety)
       option :sandbox, true
 
       option :client_options, {
-        site: "https://appcenter.intuit.com",
-        authorize_url: "/connect/oauth2",
-        token_url: "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer"
+        site: 'https://appcenter.intuit.com',
+        authorize_url: '/connect/oauth2',
+        token_url: 'https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer'
       }
 
       # Use realmId (company ID) as the unique identifier
@@ -40,20 +40,20 @@ module OmniAuth
 
       info do
         {
-          email: raw_info["email"],
-          first_name: raw_info["givenName"],
-          last_name: raw_info["familyName"],
+          email: raw_info['email'],
+          first_name: raw_info['givenName'],
+          last_name: raw_info['familyName'],
           name: full_name,
-          phone: raw_info["phoneNumber"],
+          phone: raw_info['phoneNumber'],
           realm_id: realm_id
         }
       end
 
       credentials do
-        hash = { "token" => access_token.token }
-        hash["refresh_token"] = access_token.refresh_token if access_token.refresh_token
-        hash["expires_at"] = access_token.expires_at if access_token.expires_at
-        hash["expires"] = access_token.expires?
+        hash = { 'token' => access_token.token }
+        hash['refresh_token'] = access_token.refresh_token if access_token.refresh_token
+        hash['expires_at'] = access_token.expires_at if access_token.expires_at
+        hash['expires'] = access_token.expires?
         hash
       end
 
@@ -78,12 +78,12 @@ module OmniAuth
 
       # The QuickBooks company ID (realmId)
       def realm_id
-        request.params["realmId"]
+        request.params['realmId']
       end
 
       # Construct full name from OpenID info
       def full_name
-        name = [raw_info["givenName"], raw_info["familyName"]].compact.join(" ")
+        name = [raw_info['givenName'], raw_info['familyName']].compact.join(' ')
         name.empty? ? nil : name
       end
 
@@ -101,13 +101,13 @@ module OmniAuth
 
       # Check if OpenID scopes were requested
       def openid_scope_requested?
-        scope = options[:scope] || ""
-        scope.split(/\s+/).include?("openid")
+        scope = options[:scope] || ''
+        scope.split(/\s+/).include?('openid')
       end
 
       # Get the appropriate userinfo URL based on environment
       def userinfo_url
-        domain = options[:sandbox] ? "sandbox-accounts.platform.intuit.com" : "accounts.platform.intuit.com"
+        domain = options[:sandbox] ? 'sandbox-accounts.platform.intuit.com' : 'accounts.platform.intuit.com'
         "https://#{domain}/v1/openid_connect/userinfo"
       end
     end

data/lib/omniauth-quickbooks-oauth2-modern.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
 
-require "omniauth/quickbooks_oauth2_modern/version"
-require "omniauth/strategies/quickbooks_oauth2_modern"
+require 'omniauth/quickbooks_oauth2_modern/version'
+require 'omniauth/quickbooks_oauth2_modern/token_client'
+require 'omniauth/strategies/quickbooks_oauth2_modern'

data/omniauth-quickbooks-oauth2-modern.gemspec

@@ -1,24 +1,25 @@
 # frozen_string_literal: true
 
-require_relative "lib/omniauth/quickbooks_oauth2_modern/version"
+require_relative 'lib/omniauth/quickbooks_oauth2_modern/version'
 
 Gem::Specification.new do |spec|
-  spec.name = "omniauth-quickbooks-oauth2-modern"
+  spec.name = 'omniauth-quickbooks-oauth2-modern'
   spec.version = OmniAuth::QuickbooksOauth2Modern::VERSION
-  spec.authors = ["dan1d"]
-  spec.email = ["dan@theowner.me"]
+  spec.authors = ['dan1d']
+  spec.email = ['dan@theowner.me']
 
-  spec.summary = "OmniAuth strategy for QuickBooks Online OAuth 2.0 (OmniAuth 2.0+ compatible)"
-  spec.description = "An OmniAuth strategy for authenticating with QuickBooks Online using OAuth 2.0. " \
-                     "Compatible with OmniAuth 2.0+ and supports both sandbox and production environments " \
-                     "with OpenID Connect userinfo fetching."
-  spec.homepage = "https://github.com/dan1d/omniauth-quickbooks-oauth2-modern"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.0.0"
+  spec.summary = 'OmniAuth strategy for QuickBooks Online OAuth 2.0 (OmniAuth 2.0+ compatible)'
+  spec.description = 'An OmniAuth strategy for authenticating with QuickBooks Online using OAuth 2.0. ' \
+                     'Compatible with OmniAuth 2.0+ and supports both sandbox and production environments ' \
+                     'with OpenID Connect userinfo fetching.'
+  spec.homepage = 'https://github.com/dan1d/omniauth-quickbooks-oauth2-modern'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.0.0'
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = spec.homepage
-  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
@@ -26,22 +27,22 @@ Gem::Specification.new do |spec|
         f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
     end
   end
-  spec.bindir = "exe"
+  spec.bindir = 'exe'
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
   # Runtime dependencies
-  spec.add_dependency "faraday", ">= 1.0", "< 3.0"
-  spec.add_dependency "omniauth", "~> 2.0"
-  spec.add_dependency "omniauth-oauth2", "~> 1.8"
+  spec.add_dependency 'faraday', '>= 1.0', '< 3.0'
+  spec.add_dependency 'omniauth', '~> 2.0'
+  spec.add_dependency 'omniauth-oauth2', '~> 1.8'
 
   # Development dependencies
-  spec.add_development_dependency "bundler", "~> 2.0"
-  spec.add_development_dependency "rack-test", "~> 2.1"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rspec", "~> 3.12"
-  spec.add_development_dependency "rubocop", "~> 1.50"
-  spec.add_development_dependency "rubocop-rspec", "~> 2.20"
-  spec.add_development_dependency "simplecov", "~> 0.22"
-  spec.add_development_dependency "webmock", "~> 3.18"
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rack-test', '~> 2.1'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.12'
+  spec.add_development_dependency 'rubocop', '~> 1.50'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.20'
+  spec.add_development_dependency 'simplecov', '~> 0.22'
+  spec.add_development_dependency 'webmock', '~> 3.18'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniauth-quickbooks-oauth2-modern
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - dan1d
@@ -185,6 +185,7 @@ files:
 - README.md
 - Rakefile
 - lib/omniauth-quickbooks-oauth2-modern.rb
+- lib/omniauth/quickbooks_oauth2_modern/token_client.rb
 - lib/omniauth/quickbooks_oauth2_modern/version.rb
 - lib/omniauth/strategies/quickbooks_oauth2_modern.rb
 - omniauth-quickbooks-oauth2-modern.gemspec
@@ -195,6 +196,7 @@ metadata:
   homepage_uri: https://github.com/dan1d/omniauth-quickbooks-oauth2-modern
   source_code_uri: https://github.com/dan1d/omniauth-quickbooks-oauth2-modern
   changelog_uri: https://github.com/dan1d/omniauth-quickbooks-oauth2-modern/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib