omniauth-wave-oauth2 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d1d923ae112d2a304e298303b75f9b9d62686fa67f112fa5933a0450b2efd637
+  data.tar.gz: 30c55761978e96f322632a9cde4668da910ffa85b4ae2f707b8aad119ca4de87
+SHA512:
+  metadata.gz: ebc7827b9e163a3d93c0f429be55eb3ec4384231c57d7be0a36b84c12813242505703ea2854b378804d5d6d89661e5240906da9cb1160db0221980c27f0d9ff5
+  data.tar.gz: ef442fb36327f6d5f160f053d432ced163e4f4c2d4a0a3c0ef0c1a5e1d7f66e35f1e71f33301757686735e9985ac7fee714655ebd8e529c8d16e4a5bc8c2d444

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [1.0.0] - 2026-03-13
+
+### Added
+- Initial release
+- OmniAuth OAuth2 strategy for Wave (by H&R Block)
+- GraphQL-based user and business info fetching
+- TokenClient for refreshing tokens outside the OmniAuth flow
+- Support for `account:read`, `business:read`, `user:read` scopes

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dan1d
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,180 @@
+# OmniAuth Wave OAuth2 Strategy
+
+[![Gem Version](https://badge.fury.io/rb/omniauth-wave-oauth2.svg)](https://badge.fury.io/rb/omniauth-wave-oauth2)
+
+An OmniAuth strategy for authenticating with [Wave](https://www.waveapps.com/) (by H&R Block) using OAuth 2.0.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'omniauth-wave-oauth2'
+```
+
+Then execute:
+
+```bash
+$ bundle install
+```
+
+## Wave Developer Setup
+
+1. Sign up at [Wave](https://www.waveapps.com/) and create a business
+2. Go to the [Wave Developer Portal](https://developer.waveapps.com/hc/en-us/articles/360019762711-Manage-Applications)
+3. Create a new application
+4. Note your **Client ID** and **Client Secret**
+5. Add your **Redirect URI** (e.g., `https://yourapp.com/auth/wave_oauth2/callback`)
+
+**Note:** Wave requires a [Pro Plan](https://www.waveapps.com/pricing) ($19/mo) for third-party API access.
+
+## Usage
+
+### Standalone OmniAuth
+
+```ruby
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :wave_oauth2, ENV['WAVE_CLIENT_ID'], ENV['WAVE_CLIENT_SECRET']
+end
+```
+
+### With Devise
+
+In `config/initializers/devise.rb`:
+
+```ruby
+config.omniauth :wave_oauth2, ENV['WAVE_CLIENT_ID'], ENV['WAVE_CLIENT_SECRET']
+```
+
+Add to your routes:
+
+```ruby
+devise_for :users, controllers: { omniauth_callbacks: 'users/omniauth_callbacks' }
+```
+
+Create the callbacks controller:
+
+```ruby
+class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
+  def wave_oauth2
+    @user = User.from_omniauth(request.env['omniauth.auth'])
+
+    if @user.persisted?
+      sign_in_and_redirect @user, event: :authentication
+    else
+      redirect_to new_user_registration_url
+    end
+  end
+end
+```
+
+## Auth Hash
+
+Here's an example of the authentication hash available in `request.env['omniauth.auth']`:
+
+```ruby
+{
+  "provider" => "wave_oauth2",
+  "uid" => "QnVzaW5lc3M6abc123def456",
+  "info" => {
+    "email" => "owner@example.com",
+    "name" => "Jane Doe",
+    "first_name" => "Jane",
+    "last_name" => "Doe",
+    "business_name" => "Jane's Bakery"
+  },
+  "credentials" => {
+    "token" => "ACCESS_TOKEN",
+    "refresh_token" => "REFRESH_TOKEN",
+    "expires_at" => 1704067200,
+    "expires" => true
+  },
+  "extra" => {
+    "raw_info" => {
+      "user_id" => "user-abc",
+      "email" => "owner@example.com",
+      "first_name" => "Jane",
+      "last_name" => "Doe",
+      "name" => "Jane Doe",
+      "business_id" => "QnVzaW5lc3M6abc123def456",
+      "business_name" => "Jane's Bakery"
+    }
+  }
+}
+```
+
+## Wave OAuth2 Specifics
+
+- **GraphQL API**: Wave uses a GraphQL API at `gql.waveapps.com/graphql/public` (not REST). User and business info are fetched via GraphQL after token exchange.
+- **Auth Scheme**: Wave requires credentials in the POST body (`auth_scheme: :request_body`), not HTTP Basic Auth.
+- **Token Expiry**: Access tokens expire after ~2 hours. Refresh tokens are long-lived.
+- **UID**: The `uid` is the Wave Business ID (Base64-encoded format like `QnVzaW5lc3M6...`). Falls back to User ID if no business exists.
+- **Scopes**: Requests `account:read business:read user:read` by default.
+
+## Token Refresh
+
+Wave access tokens expire after ~2 hours. This gem includes a `TokenClient` for refreshing tokens:
+
+```ruby
+client = OmniAuth::WaveOauth2::TokenClient.new(
+  client_id: ENV['WAVE_CLIENT_ID'],
+  client_secret: ENV['WAVE_CLIENT_SECRET']
+)
+
+result = client.refresh_token(account.refresh_token)
+
+if result.success?
+  account.update!(
+    access_token: result.access_token,
+    refresh_token: result.refresh_token,
+    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.token_expires_at)
+
+# Custom buffer (e.g., refresh 10 minutes before expiry)
+client.token_expired?(account.token_expires_at, buffer_seconds: 600)
+```
+
+### TokenResult Object
+
+| 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 Wave |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/dan1d/omniauth-wave-oauth2.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin feature/my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/omniauth/strategies/wave_oauth2.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'omniauth-oauth2'
+require 'faraday'
+require 'json'
+
+module OmniAuth
+  module Strategies
+    # OmniAuth strategy for Wave (by H&R Block) OAuth2.
+    #
+    # Wave uses standard OAuth2 with ~2-hour access tokens and refresh tokens.
+    # The authorize and token endpoints are on api.waveapps.com.
+    # API data is fetched via GraphQL at gql.waveapps.com/graphql/public.
+    #
+    # Note: Requires Wave Pro Plan ($19/mo) for third-party API access.
+    #
+    # @example Basic usage
+    #   provider :wave_oauth2, ENV['WAVE_CLIENT_ID'], ENV['WAVE_CLIENT_SECRET']
+    #
+    # @example With Devise
+    #   config.omniauth :wave_oauth2, ENV['WAVE_CLIENT_ID'], ENV['WAVE_CLIENT_SECRET']
+    #
+    class WaveOauth2 < OmniAuth::Strategies::OAuth2
+      option :name, 'wave_oauth2'
+
+      option :client_options, {
+        site: 'https://api.waveapps.com',
+        authorize_url: '/oauth2/authorize/',
+        token_url: '/oauth2/token/',
+        auth_scheme: :request_body
+      }
+
+      option :authorize_params, {
+        scope: 'account:read business:read user:read'
+      }
+
+      # UID is the Wave business ID (primary identifier for the connected account)
+      uid { raw_info['business_id'] || raw_info['user_id'] }
+
+      info do
+        {
+          email: raw_info['email'],
+          name: raw_info['name'],
+          first_name: raw_info['first_name'],
+          last_name: raw_info['last_name'],
+          business_name: raw_info['business_name']
+        }
+      end
+
+      extra do
+        { raw_info: raw_info }
+      end
+
+      def raw_info
+        @raw_info ||= fetch_user_and_business_info
+      end
+
+      # Override to strip query params from callback_url for redirect_uri matching.
+      # Wave requires the redirect_uri to match exactly.
+      def build_access_token
+        redirect_uri = callback_url.sub(/\?.*/, '')
+        log(:info, "Token exchange — site: #{client.site}, redirect_uri: #{redirect_uri}")
+        verifier = request.params['code']
+        client.auth_code.get_token(
+          verifier,
+          { redirect_uri: redirect_uri }.merge(token_params.to_hash(symbolize_keys: true)),
+          deep_symbolize(options.auth_token_params)
+        )
+      rescue ::OAuth2::Error => e
+        log(:error, "Token exchange FAILED: status=#{e.response&.status} body=#{e.response&.body}")
+        raise
+      end
+
+      private
+
+      GRAPHQL_URL = 'https://gql.waveapps.com/graphql/public'
+
+      USER_QUERY = <<~GRAPHQL
+        query {
+          user {
+            id
+            firstName
+            lastName
+            defaultEmail
+          }
+          businesses(page: 1, pageSize: 1) {
+            edges {
+              node {
+                id
+                name
+              }
+            }
+          }
+        }
+      GRAPHQL
+
+      def fetch_user_and_business_info
+        response = access_token.post(GRAPHQL_URL, {
+                                       body: { query: USER_QUERY }.to_json,
+                                       headers: { 'Content-Type' => 'application/json' }
+                                     })
+
+        data = JSON.parse(response.body)['data'] || {}
+        user = data['user'] || {}
+        business = data.dig('businesses', 'edges', 0, 'node') || {}
+
+        {
+          'user_id' => user['id'],
+          'email' => user['defaultEmail'],
+          'first_name' => user['firstName'],
+          'last_name' => user['lastName'],
+          'name' => [user['firstName'], user['lastName']].compact.join(' '),
+          'business_id' => business['id'],
+          'business_name' => business['name']
+        }
+      rescue StandardError => e
+        log(:warn, "Failed to fetch user/business info: #{e.message}")
+        { 'user_id' => nil }
+      end
+
+      def log(level, message)
+        return unless defined?(OmniAuth.logger) && OmniAuth.logger
+
+        OmniAuth.logger.send(level, "[WaveOauth2] #{message}")
+      end
+    end
+  end
+end

data/lib/omniauth/wave_oauth2/token_client.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module OmniAuth
+  module WaveOauth2
+    # Client for managing Wave OAuth2 tokens outside the OmniAuth flow.
+    #
+    # Wave access tokens expire after ~2 hours. Use this client to refresh
+    # tokens in background jobs or API services.
+    #
+    # @example Basic usage
+    #   client = OmniAuth::WaveOauth2::TokenClient.new(
+    #     client_id: ENV['WAVE_CLIENT_ID'],
+    #     client_secret: ENV['WAVE_CLIENT_SECRET']
+    #   )
+    #
+    #   result = client.refresh_token(account.refresh_token)
+    #   if result.success?
+    #     account.update!(
+    #       access_token: result.access_token,
+    #       refresh_token: result.refresh_token,
+    #       token_expires_at: Time.at(result.expires_at)
+    #     )
+    #   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
+
+      TOKEN_URL = 'https://api.waveapps.com/oauth2/token/'
+
+      attr_reader :client_id, :client_secret
+
+      # Initialize a new TokenClient
+      #
+      # @param client_id [String] Your Wave App Client ID
+      # @param client_secret [String] Your Wave 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)
+        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
+
+      private
+
+      def make_refresh_request(refresh_token)
+        Faraday.post(TOKEN_URL) do |req|
+          req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
+          req.headers['Accept'] = 'application/json'
+          req.body = URI.encode_www_form(
+            grant_type: 'refresh_token',
+            client_id: client_id,
+            client_secret: client_secret,
+            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
+          { 'message' => 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/wave_oauth2/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module OmniAuth
+  module WaveOauth2
+    VERSION = '1.0.0'
+  end
+end

data/lib/omniauth-wave-oauth2.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'omniauth-oauth2'
+require 'omniauth/wave_oauth2/version'
+require 'omniauth/wave_oauth2/token_client'
+require 'omniauth/strategies/wave_oauth2'

metadata

@@ -0,0 +1,198 @@
+--- !ruby/object:Gem::Specification
+name: omniauth-wave-oauth2
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- dan1d
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: omniauth-oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+description: An OmniAuth strategy for authenticating with Wave accounting (by H&R
+  Block) using OAuth 2.0. Fetches user and business info via Wave's GraphQL API.
+email:
+- dan1d@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/omniauth-wave-oauth2.rb
+- lib/omniauth/strategies/wave_oauth2.rb
+- lib/omniauth/wave_oauth2/token_client.rb
+- lib/omniauth/wave_oauth2/version.rb
+homepage: https://github.com/dan1d/omniauth-wave-oauth2
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/dan1d/omniauth-wave-oauth2
+  source_code_uri: https://github.com/dan1d/omniauth-wave-oauth2
+  changelog_uri: https://github.com/dan1d/omniauth-wave-oauth2/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: OmniAuth OAuth2 strategy for Wave (by H&R Block)
+test_files: []