omniauth-clover-oauth2 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 718583b3f5599a91cb7c93b32f01af9ac8a658e3e351b4c601b9e5319a1345a3
-  data.tar.gz: 152836810576c0efa3c17d4da5c56bfe6cda667f9a25c40e80fddd2ef1235081
+  metadata.gz: fb709fb251b03d2c45fce7d93faeaaea36f310b2f6fa3250122714834df7a7c1
+  data.tar.gz: eda34b1fe80cfb8b5ef604e161c82a3490b914042f8579cb19e9e98ad54d8d71
 SHA512:
-  metadata.gz: 536d7e5a16bc73d381686f44ea96eeac9bf1225d6830a1a42aab054aeaf49552fcb48790cccb7473d4eed00f33b9521a71d9aab2906aed10a98a747c8b29d78e
-  data.tar.gz: a6f5190005c3f2ec1e1cdec91991728bd2b3ba11fda0f67e121bf05016ff10703d00e0e1e14aef83fd2f704c80e09ed3abef7dfb0d4d9c8cb29d8f112a80313b
+  metadata.gz: 70e02544685ecc4e933c4ff32509563bd42790915b1993da626d684ebe0d906524f13328a0d5c0be0f20151322268f38ae6c12cdf379d306cb9ddf87f35a7666
+  data.tar.gz: 6de45329ff4570f9cfef702a162a8375b04e4f37f38ad5456736d74ef5721e03c3a53ca389b289f790c535296a9eeaecd5a34d54f58b457a7a723b861c110576

data/CHANGELOG.md

@@ -5,7 +5,29 @@ 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.0.0] - 2024-01-30
+## [1.1.1] - 2026-01-31
+
+### Fixed
+
+- TokenClient now uses correct Clover OAuth v2 refresh endpoint (`/oauth/v2/refresh`)
+- Fixed expiration parsing to handle Unix timestamps from Clover
+
+## [1.1.0] - 2026-01-30
+
+### 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
+
+## [1.0.1] - 2026-01-30
+
+### Fixed
+
+- Minor documentation and metadata updates
+
+## [1.0.0] - 2026-01-30
 
 ### Added
 

data/README.md

@@ -231,7 +231,100 @@ end
 
 ## Token Refresh
 
-Clover access tokens expire (typically after 1 year, but check your app settings). To refresh tokens, you'll need to implement token refresh logic using the Clover API directly.
+Clover access tokens expire (typically after 1 year, but check your app settings). This gem includes a `TokenClient` class to easily refresh tokens in your Rails app.
+
+### Basic Usage
+
+```ruby
+# Create a client instance
+client = OmniAuth::CloverOauth2::TokenClient.new(
+  client_id: ENV['CLOVER_CLIENT_ID'],
+  client_secret: ENV['CLOVER_CLIENT_SECRET'],
+  sandbox: Rails.env.development?
+)
+
+# Refresh an expired token
+result = client.refresh_token(user.clover_refresh_token)
+
+if result.success?
+  user.update!(
+    clover_access_token: result.access_token,
+    clover_refresh_token: result.refresh_token,
+    clover_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?(user.clover_token_expires_at)
+
+# Custom buffer (e.g., refresh 1 hour before expiry)
+client.token_expired?(user.clover_token_expires_at, buffer_seconds: 3600)
+```
+
+### Rails Service Example
+
+```ruby
+# app/services/clover_api_service.rb
+class CloverApiService
+  def initialize(user)
+    @user = user
+    @client = OmniAuth::CloverOauth2::TokenClient.new(
+      client_id: ENV['CLOVER_CLIENT_ID'],
+      client_secret: ENV['CLOVER_CLIENT_SECRET'],
+      sandbox: !Rails.env.production?
+    )
+  end
+
+  def with_valid_token
+    refresh_if_expired!
+    yield @user.clover_access_token
+  end
+
+  private
+
+  def refresh_if_expired!
+    return unless @client.token_expired?(@user.clover_token_expires_at)
+
+    result = @client.refresh_token(@user.clover_refresh_token)
+    raise "Token refresh failed: #{result.error}" unless result.success?
+
+    @user.update!(
+      clover_access_token: result.access_token,
+      clover_refresh_token: result.refresh_token,
+      clover_token_expires_at: Time.at(result.expires_at)
+    )
+  end
+end
+
+# Usage
+CloverApiService.new(current_user).with_valid_token do |token|
+  # Make API calls with valid token
+  response = Faraday.get("https://api.clover.com/v3/merchants/#{merchant_id}") do |req|
+    req.headers['Authorization'] = "Bearer #{token}"
+  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 Clover |
 
 ## Contributing
 

data/lib/omniauth/clover_oauth2/token_client.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module OmniAuth
+  module CloverOauth2
+    # Client for managing Clover OAuth2 tokens
+    #
+    # This class provides an easy way to refresh expired tokens in your Rails app.
+    #
+    # @example Basic usage
+    #   client = OmniAuth::CloverOauth2::TokenClient.new(
+    #     client_id: ENV['CLOVER_CLIENT_ID'],
+    #     client_secret: ENV['CLOVER_CLIENT_SECRET'],
+    #     sandbox: Rails.env.development?
+    #   )
+    #
+    #   # Refresh an expired token
+    #   result = client.refresh_token(user.clover_refresh_token)
+    #   if result.success?
+    #     user.update!(
+    #       clover_access_token: result.access_token,
+    #       clover_refresh_token: result.refresh_token,
+    #       clover_token_expires_at: result.expires_at
+    #     )
+    #   end
+    #
+    # @example With automatic token refresh in a service
+    #   class CloverApiService
+    #     def initialize(user)
+    #       @user = user
+    #       @client = OmniAuth::CloverOauth2::TokenClient.new(
+    #         client_id: ENV['CLOVER_CLIENT_ID'],
+    #         client_secret: ENV['CLOVER_CLIENT_SECRET']
+    #       )
+    #     end
+    #
+    #     def with_valid_token
+    #       refresh_if_expired!
+    #       yield @user.clover_access_token
+    #     end
+    #
+    #     private
+    #
+    #     def refresh_if_expired!
+    #       return unless @user.clover_token_expired?
+    #
+    #       result = @client.refresh_token(@user.clover_refresh_token)
+    #       raise "Token refresh failed: #{result.error}" unless result.success?
+    #
+    #       @user.update!(
+    #         clover_access_token: result.access_token,
+    #         clover_refresh_token: result.refresh_token,
+    #         clover_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
+
+      # OAuth v2 refresh uses the API domain with /oauth/v2/refresh
+      SANDBOX_API_URL = 'https://apisandbox.dev.clover.com'
+      PRODUCTION_API_URL = 'https://api.clover.com'
+      EU_API_URL = 'https://api.eu.clover.com'
+      LA_API_URL = 'https://api.la.clover.com'
+
+      attr_reader :client_id, :client_secret, :sandbox
+
+      # Initialize a new TokenClient
+      #
+      # @param client_id [String] Your Clover App ID
+      # @param client_secret [String] Your Clover App Secret
+      # @param sandbox [Boolean] Use sandbox environment (default: true)
+      def initialize(client_id:, client_secret:, sandbox: true)
+        @client_id = client_id
+        @client_secret = client_secret
+        @sandbox = sandbox
+      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)
+        return TokenResult.new(success: false, error: 'Refresh token is required') if refresh_token.nil? || refresh_token.empty?
+
+        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
+
+      # Get the API base URL based on sandbox setting
+      #
+      # @return [String] The API base URL
+      def api_base_url
+        sandbox ? SANDBOX_API_URL : PRODUCTION_API_URL
+      end
+
+      private
+
+      def make_refresh_request(refresh_token)
+        # Clover OAuth v2 refresh endpoint uses JSON body
+        # Endpoint: /oauth/v2/refresh
+        # Required params: client_id, refresh_token
+        Faraday.post(refresh_url) do |req|
+          req.headers['Content-Type'] = 'application/json'
+          req.headers['Accept'] = 'application/json'
+          req.body = {
+            client_id: client_id,
+            refresh_token: refresh_token
+          }.to_json
+        end
+      end
+
+      def refresh_url
+        # OAuth v2 uses /oauth/v2/refresh endpoint
+        "#{api_base_url}/oauth/v2/refresh"
+      end
+
+      def parse_success_response(response)
+        data = JSON.parse(response.body)
+
+        # Clover OAuth v2 returns 'access_token_expiration' as Unix timestamp
+        # It may also return 'expires_in' as seconds in some contexts
+        raw_expiration = data['access_token_expiration'] || data['expires_in']
+
+        # Determine if it's a timestamp (large number) or seconds (small number)
+        # Unix timestamps for 2024+ are > 1700000000
+        if raw_expiration && raw_expiration.to_i > 1_600_000_000
+          # It's a Unix timestamp
+          expires_at = raw_expiration.to_i
+          expires_in = expires_at - Time.now.to_i
+        elsif raw_expiration
+          # It's seconds until expiry
+          expires_in = raw_expiration.to_i
+          expires_at = Time.now.to_i + expires_in
+        else
+          expires_in = nil
+          expires_at = nil
+        end
+
+        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
+          { 'message' => response.body }
+        end
+
+        error_message = error_data['message'] || error_data['error'] || "HTTP #{response.status}"
+
+        TokenResult.new(
+          success: false,
+          error: error_message,
+          raw_response: error_data
+        )
+      end
+    end
+  end
+end

data/lib/omniauth/clover_oauth2/version.rb

@@ -2,6 +2,6 @@
 
 module OmniAuth
   module CloverOauth2
-    VERSION = '1.0.0'
+    VERSION = '1.1.1'
   end
 end

data/lib/omniauth-clover-oauth2.rb

@@ -2,4 +2,5 @@
 
 require 'omniauth-oauth2'
 require 'omniauth/clover_oauth2/version'
+require 'omniauth/clover_oauth2/token_client'
 require 'omniauth/strategies/clover_oauth2'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniauth-clover-oauth2
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - dan1d
@@ -181,6 +181,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/omniauth-clover-oauth2.rb
+- lib/omniauth/clover_oauth2/token_client.rb
 - lib/omniauth/clover_oauth2/version.rb
 - lib/omniauth/strategies/clover_oauth2.rb
 homepage: https://github.com/dan1d/omniauth-clover-oauth2