booqable 1.0.0

data/lib/booqable/auth.rb

@@ -0,0 +1,114 @@
+module Booqable
+  # Authentication methods for {Booqable::Client}
+  #
+  # Provides authentication support for multiple methods including OAuth2,
+  # API keys, and single-use tokens. The module automatically detects which
+  # authentication method to use based on the configured credentials.
+  #
+  # @example OAuth authentication
+  #   client = Booqable::Client.new(
+  #     client_id: "your_client_id",
+  #     client_secret: "your_client_secret"
+  #   )
+  #   client.authenticate_with_code("auth_code_from_callback")
+  #
+  # @example API key authentication
+  #   client = Booqable::Client.new(api_key: "your_api_key")
+  #   # Authentication is automatic with API requests
+  #
+  # @example Single-use token authentication
+  #   client = Booqable::Client.new(
+  #     single_use_token: "your_token",
+  #     single_use_token_algorithm: "HS256",
+  #     single_use_token_secret: "your_secret"
+  #   )
+  module Auth
+    # Complete OAuth authentication flow with authorization code
+    #
+    # Exchanges an authorization code for an access token and stores it
+    # using the configured write_token proc. This method should be called
+    # after the user has been redirected back from the OAuth provider.
+    #
+    # @param code [String] Authorization code from OAuth callback
+    # @return [void]
+    # @raise [OAuth2::Error] If the authorization code is invalid or expired
+    #
+    # @example
+    #   # In your OAuth callback handler
+    #   client.authenticate_with_code(params[:code])
+    def authenticate_with_code(code)
+      token = oauth_client.get_token_from_code(code)
+      @write_token.call(token.to_hash)
+    end
+
+    # Inject appropriate authentication middleware into the request stack
+    #
+    # Automatically detects which authentication method is configured and
+    # injects the corresponding middleware. Multiple authentication methods
+    # can be configured, with OAuth taking precedence over API keys.
+    #
+    # @param builder [Faraday::Builder] The middleware builder to configure
+    # @return [void]
+    # @api private
+    def inject_auth_middleware(builder)
+      builder.use Booqable::Middleware::Auth::OAuth, {
+        client_id: client_id,
+        client_secret: client_secret,
+        api_endpoint: api_endpoint,
+        redirect_uri: redirect_uri,
+        read_token: read_token,
+        write_token: write_token
+      } if oauth_authenticated?
+
+      builder.use Booqable::Middleware::Auth::ApiKey, {
+        api_key: api_key
+      } if api_key_authenticated?
+
+      builder.use Booqable::Middleware::Auth::SingleUse, {
+        single_use_token: single_use_token,
+        single_use_token_algorithm: single_use_token_algorithm,
+        single_use_token_private_key: single_use_token_private_key || single_use_token_secret,
+        single_use_token_expiration_period: single_use_token_expiration_period,
+        single_use_token_company_id: single_use_token_company_id,
+        single_use_token_user_id: single_use_token_user_id,
+        api_endpoint: api_endpoint
+      } if single_use_token_authenticated?
+    end
+
+    # Get or create the OAuth client
+    #
+    # Returns a memoized OAuth client instance configured with the current
+    # client credentials. Returns nil if OAuth is not configured.
+    #
+    # @return [OAuthClient, nil] OAuth client instance or nil if not configured
+    def oauth_client
+      @oauth_client ||= OAuthClient.new(
+        api_endpoint: api_endpoint,
+        client_id: @client_id,
+        client_secret: @client_secret,
+        redirect_uri: @redirect_uri
+      ) if oauth_authenticated?
+    end
+
+    # Check if OAuth authentication is configured
+    #
+    # @return [Boolean] true if both client_id and client_secret are present
+    def oauth_authenticated?
+      !!@client_id && !!@client_secret
+    end
+
+    # Check if API key authentication is configured
+    #
+    # @return [Boolean] true if api_key is present
+    def api_key_authenticated?
+      !!@api_key
+    end
+
+    # Check if single-use token authentication is configured
+    #
+    # @return [Boolean] true if single_use_token is present
+    def single_use_token_authenticated?
+      !!@single_use_token
+    end
+  end
+end

data/lib/booqable/client.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Booqable
+  # Client for the Booqable API
+  #
+  # Provides a Ruby interface to interact with the Booqable rental management API.
+  # The client can be configured with various authentication methods including
+  # API keys, OAuth, and single-use tokens.
+  #
+  # @example Initialize with API key
+  #   client = Booqable::Client.new(
+  #     api_key: "your_api_key",
+  #     company_id: "your_company_id"
+  #   )
+  #
+  # @example Initialize with OAuth
+  #   client = Booqable::Client.new(
+  #     client_id: "your_client_id",
+  #     client_secret: "your_client_secret",
+  #     company_id: "your_company_id"
+  #   )
+  #
+  # @see https://developers.booqable.com/
+  class Client
+    include Booqable::Configurable
+    include Booqable::Resources
+    include Booqable::Auth
+    include Booqable::HTTP
+
+    # List of configuration keys that contain sensitive information
+    # and should be masked in inspect output
+    SECRETS = %w[
+      client_secret
+      client_id
+      api_key
+      single_use_token
+      single_use_token_private_key
+      single_use_token_secret
+      refresh_token
+      access_token
+    ]
+
+    # Initialize a new Client
+    #
+    # @param options [Hash] Configuration options for the client
+    # @see Booqable::Configurable For a complete list of supported configuration options
+    def initialize(options = {})
+      # Use options passed in, but fall back to module defaults
+      #
+      # This may look like a `.keys.each` which should be replaced with `#each_key`, but
+      # this doesn't actually work, since `#keys` is just a method we've defined ourselves.
+      # The class doesn't fulfill the whole `Enumerable` contract.
+      Booqable::Configurable.keys.each do |key|
+        value = options[key].nil? ? Booqable.instance_variable_get(:"@#{key}") : options[key]
+        instance_variable_set(:"@#{key}", value)
+      end
+    end
+
+    # String representation of the client with sensitive information masked
+    #
+    # Overrides the default inspect method to hide sensitive configuration
+    # values like API keys, client secrets, and tokens by replacing them
+    # with asterisks.
+    #
+    # @return [String] String representation with secrets masked
+    # @example
+    #   client = Booqable::Client.new(api_key: "secret123")
+    #   client.inspect #=> "#<Booqable::Client:0x... @api_key=\"*********\">"
+    def inspect
+      inspected = super
+
+      secrets = SECRETS.map { |secret| instance_variable_get("@#{secret}") }
+
+      inspected.gsub!(/"(#{secrets.join("|")})"/) do |match|
+        match.gsub!(/./, "*")
+      end
+
+      inspected
+    end
+  end
+end

data/lib/booqable/configurable.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Booqable
+  # Configuration options for {Client}, defaulting to values
+  # in {Default}
+  module Configurable
+    # @!attribute api_endpoint
+    #   @return [String] Base URL for API requests. default: https://company.booqable.com/api/4
+    # @!attribute auto_paginate
+    #   @return [Boolean] Auto fetch next page of results until rate limit reached
+    # @!attribute client_id
+    #   @return [String] Configure OAuth app key
+    # @!attribute [w] client_secret
+    #   @return [String] Configure OAuth app secret
+    # @!attribute default_media_type
+    #   @return [String] Configure preferred media type (for API versioning, for example)
+    # @!attribute connection_options
+    #   @see https://github.com/lostisland/faraday
+    #   @return [Hash] Configure connection options for Faraday
+    # @!attribute middleware
+    #   @see https://github.com/lostisland/faraday
+    #   @return [Faraday::Builder or Faraday::RackBuilder] Configure middleware for Faraday
+    # @!attribute per_page
+    #   @return [String] Configure page size for paginated results. API default: 25
+    # @!attribute proxy
+    #   @see https://github.com/lostisland/faraday
+    #   @return [String] URI for proxy server
+    # @!attribute ssl_verify_mode
+    #   @see https://github.com/lostisland/faraday
+    #   @return [String] SSL verify mode for ssl connections
+    # @!attribute user_agent
+    #   @return [String] Configure User-Agent header for requests.
+
+    attr_accessor :api_domain,
+                  :api_endpoint,
+                  :api_key,
+                  :api_version,
+                  :auto_paginate,
+                  :client_id,
+                  :client_secret,
+                  :company_id,
+                  :connection_options,
+                  :debug,
+                  :default_media_type,
+                  :middleware,
+                  :no_retries,
+                  :per_page,
+                  :proxy,
+                  :read_token,
+                  :redirect_uri,
+                  :single_use_token,
+                  :single_use_token_algorithm,
+                  :single_use_token_company_id,
+                  :single_use_token_expiration_period,
+                  :single_use_token_private_key,
+                  :single_use_token_secret,
+                  :single_use_token_user_id,
+                  :ssl_verify_mode,
+                  :user_agent,
+                  :write_token
+
+    class << self
+      # List of configurable keys for {Booqable::Client}
+      # @return [Array] of option keys
+      def keys
+        @keys ||= %i[
+          api_domain
+          api_endpoint
+          api_key
+          api_version
+          auto_paginate
+          client_id
+          client_secret
+          company_id
+          connection_options
+          debug
+          default_media_type
+          middleware
+          no_retries
+          per_page
+          proxy
+          read_token
+          redirect_uri
+          single_use_token
+          single_use_token_algorithm
+          single_use_token_company_id
+          single_use_token_expiration_period
+          single_use_token_private_key
+          single_use_token_secret
+          single_use_token_user_id
+          ssl_verify_mode
+          user_agent
+          write_token
+        ]
+      end
+    end
+
+    # Set configuration options using a block
+    def configure
+      yield self
+    end
+
+    # Reset configuration options to default values
+    def reset!
+      # rubocop:disable Style/HashEachMethods
+      #
+      # This may look like a `.keys.each` which should be replaced with `#each_key`, but
+      # this doesn't actually work, since `#keys` is just a method we've defined ourselves.
+      # The class doesn't fulfill the whole `Enumerable` contract.
+      Booqable::Configurable.keys.each do |key|
+        # rubocop:enable Style/HashEachMethods
+        instance_variable_set(:"@#{key}", Booqable::Default.options[key])
+      end
+      self
+    end
+    alias setup reset!
+
+    # Compares client options to a Hash of requested options
+    #
+    # @param opts [Hash] Options to compare with current client options
+    # @return [Boolean]
+    def same_options?(opts)
+      opts.hash == options.hash
+    end
+
+    # Whether to print debug information
+    #
+    # @return [Boolean] true if debug mode is enabled, false otherwise
+    def debug?
+      @debug || false
+    end
+
+    private
+
+    def api_protocol
+      @api_domain == "booqable.com" ? "https" : "http"
+    end
+
+    def options
+      Booqable::Configurable.keys.to_h { |key| [ key, instance_variable_get(:"@#{key}") ] }
+    end
+  end
+end

data/lib/booqable/default.rb

@@ -0,0 +1,215 @@
+
+module Booqable
+  # Default configuration options for {Client}
+  #
+  # Provides default values for all configuration options, with support for
+  # environment variable overrides. All defaults can be overridden by setting
+  # the appropriate environment variables.
+  #
+  # @example Environment variable configuration
+  #   ENV["BOOQABLE_API_KEY"] = "your_api_key"
+  #   ENV["BOOQABLE_COMPANY_ID"] = "your_company_id"
+  #   ENV["BOOQABLE_PER_PAGE"] = "50"
+  module Default
+    # Default User Agent header string
+    USER_AGENT   = "Booqable Ruby Gem #{Booqable::VERSION}"
+
+    # Default media type (json:api) for requests
+    MEDIA_TYPE   = "application/vnd.api+json"
+
+    # Default retry options for Faraday::Retry middleware
+    RETRY_OPTIONS = {
+      exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [ Booqable::ServerError ],
+      max: 2, # maximum number of retries (total of 3 attempts including the first)
+      interval: 2, # seconds to wait before retrying
+      interval_randomness: 0.5, # randomize the interval by this amount
+      backoff_factor: 2 # multiply the interval by this factor on each retry
+    }
+
+    # Basic middleware stack for Faraday::Connection (without authentication middleware)
+    MIDDLEWARE = Faraday::RackBuilder.new do |builder|
+      # Retry middleware
+      builder.use Faraday::Retry::Middleware, RETRY_OPTIONS
+      # Error handling middleware
+      builder.use Booqable::Middleware::RaiseError
+
+      builder.adapter Faraday.default_adapter
+    end
+
+    class << self
+      # Configuration options
+      # @return [Hash]
+      def options
+        Booqable::Configurable.keys.to_h { |key| [ key, send(key) ] }
+      end
+
+      # Default API endpoint from ENV
+      # @return [String]
+      def api_domain
+        ENV.fetch("BOOQABLE_API_DOMAIN", "booqable.com")
+      end
+
+      # Default API version from ENV
+      # @return [Integer] API version number
+      def api_version
+        ENV.fetch("BOOQABLE_API_VERSION", 4)
+      end
+
+      # Default API endpoint from ENV
+      # @return [String, nil] Full API endpoint URL or nil to construct from domain
+      def api_endpoint
+        ENV.fetch("BOOQABLE_API_ENDPOINT", nil)
+      end
+
+      # Default pagination preference from ENV
+      # @return [String]
+      def auto_paginate
+        ENV.fetch("BOOQABLE_AUTO_PAGINATE", nil)
+      end
+
+      # Default OAuth app key from ENV
+      # @return [String]
+      def client_id
+        ENV.fetch("BOOQABLE_CLIENT_ID", nil)
+      end
+
+      # Default OAuth app secret from ENV
+      # @return [String]
+      def client_secret
+        ENV.fetch("BOOQABLE_CLIENT_SECRET", nil)
+      end
+
+      # Default company ID from ENV
+      # @return [String, nil] Company identifier
+      def company_id
+        ENV.fetch("BOOQABLE_COMPANY_ID", nil)
+      end
+
+      # Default redirect URI for OAuth from ENV
+      # @return [String]
+      def redirect_uri
+        ENV.fetch("BOOQABLE_REDIRECT_URI", nil)
+      end
+
+      # Default options for Faraday::Connection
+      # @return [Hash]
+      def connection_options
+        nil
+      end
+
+      # Default media type from ENV or {MEDIA_TYPE}
+      # @return [String]
+      def default_media_type
+        ENV.fetch("BOOQABLE_DEFAULT_MEDIA_TYPE") { MEDIA_TYPE }
+      end
+
+      # Default middleware stack for Faraday::Connection
+      # from {MIDDLEWARE}
+      # @return [Faraday::RackBuilder or Faraday::Builder]
+      def middleware
+        MIDDLEWARE
+      end
+
+      # Default pagination page size from ENV
+      # @return [Integer] Page size
+      def per_page
+        page_size = ENV.fetch("BOOQABLE_PER_PAGE", 25)
+
+        page_size&.to_i
+      end
+
+      # Default proxy server URI for Faraday connection from ENV
+      # @return [String]
+      def proxy
+        ENV.fetch("BOOQABLE_PROXY", nil)
+      end
+
+      # Default SSL verify mode from ENV
+      # @return [Integer]
+      def ssl_verify_mode
+        # 0 is OpenSSL::SSL::VERIFY_NONE
+        # 1 is OpenSSL::SSL::SSL_VERIFY_PEER
+        # the standard default for SSL is SSL_VERIFY_PEER which requires a server certificate check on the client
+        ENV.fetch("BOOQABLE_SSL_VERIFY_MODE", 1).to_i
+      end
+
+      # Default User-Agent header string from ENV or {USER_AGENT}
+      # @return [String]
+      def user_agent
+        ENV.fetch("BOOQABLE_USER_AGENT") { USER_AGENT }
+      end
+
+      # Default OAuth token reader
+      # @return [Proc] Empty proc that returns nothing
+      def read_token
+        Proc.new { }
+      end
+
+      # Default OAuth token writer
+      # @return [Proc] Empty proc that does nothing
+      def write_token
+        Proc.new { }
+      end
+
+      # Default API key from ENV
+      # @return [String, nil] API key for authentication
+      def api_key
+        ENV.fetch("BOOQABLE_API_KEY", nil)
+      end
+
+      # Default single use token from ENV
+      # @return [String, nil] Single use token for authentication
+      def single_use_token
+        ENV.fetch("BOOQABLE_SINGLE_USE_TOKEN", nil)
+      end
+
+      # Default single use token algorithm from ENV
+      # @return [String, nil] Algorithm for single use token (e.g., "HS256", "RS256")
+      def single_use_token_algorithm
+        ENV.fetch("BOOQABLE_SINGLE_USE_TOKEN_ALGORITHM", nil)
+      end
+
+      # Default single use token secret from ENV
+      # @return [String, nil] Secret for HMAC single use token signing
+      def single_use_token_secret
+        ENV.fetch("BOOQABLE_SINGLE_USE_TOKEN_SECRET", nil)
+      end
+
+      # Default single use token private key from ENV
+      # @return [String, nil] Private key for RSA/ECDSA single use token signing
+      def single_use_token_private_key
+        ENV.fetch("BOOQABLE_SINGLE_USE_TOKEN_PRIVATE_KEY", nil)
+      end
+
+      # Default single use token expiration period from ENV
+      # @return [Integer] Token expiration period in seconds
+      def single_use_token_expiration_period
+        ENV.fetch("BOOQABLE_SINGLE_USE_TOKEN_EXPIRATION_PERIOD") { 10 * 60 }.to_i # default to 10 minutes
+      end
+
+      # Default single use token company ID from ENV
+      # @return [String, nil] Company ID for single use token
+      def single_use_token_company_id
+        ENV.fetch("BOOQABLE_SINGLE_USE_TOKEN_COMPANY_ID", nil)
+      end
+
+      # Default single use token user ID from ENV
+      # @return [String, nil] User ID for single use token
+      def single_use_token_user_id
+        ENV.fetch("BOOQABLE_SINGLE_USE_TOKEN_USER_ID", nil)
+      end
+
+      # Default debug mode setting
+      # @return [Boolean] Whether debug mode is enabled
+      def debug
+        false
+      end
+
+      # Default retry setting
+      # @return [Boolean] Whether to disable retries
+      def no_retries
+        false
+      end
+    end
+  end
+end