booqable 1.0.0

data/lib/booqable/middleware/auth/oauth.rb

@@ -0,0 +1,88 @@
+module Booqable
+  module Middleware
+    module Auth
+      # Faraday middleware for OAuth2 authentication
+      #
+      # This middleware handles OAuth2 token-based authentication for HTTP requests.
+      # It automatically manages access tokens, refreshing them when expired, and
+      # adds the Bearer token to the Authorization header.
+      #
+      # @example Adding to Faraday middleware stack
+      #   builder.use Booqable::Middleware::Auth::OAuth,
+      #     client_id: "your_client_id",
+      #     client_secret: "your_client_secret",
+      #     api_endpoint: "https://company.booqable.com/api/v4/oauth/token",
+      #     read_token: -> { stored_token },
+      #     write_token: ->(token) { store_token(token) }
+      class OAuth < Base
+        # Initialize the OAuth authentication middleware
+        #
+        # @param app [#call] The next middleware in the Faraday stack
+        # @param options [Hash] Configuration options
+        # @option options [String] :client_id OAuth client ID
+        # @option options [String] :client_secret OAuth client secret
+        # @option options [String] :api_endpoint API endpoint URL for the OAuth provider
+        # @option options [Proc] :read_token Proc to read stored token
+        # @option options [Proc] :write_token Proc to store new token
+        # @raise [KeyError] If required options are not provided
+        def initialize(app, options = {})
+          super(app)
+
+          @client_id = options.fetch(:client_id)
+          @client_secret = options.fetch(:client_secret)
+          @api_endpoint = options.fetch(:api_endpoint)
+          @read_token = options.fetch(:read_token)
+          @write_token = options.fetch(:write_token)
+
+          @client = OAuthClient.new(
+            client_id: @client_id,
+            client_secret: @client_secret,
+            api_endpoint: @api_endpoint,
+          )
+        end
+
+        # Process the HTTP request and add OAuth authentication
+        #
+        # Retrieves the stored access token, refreshes it if expired, and adds
+        # it to the Authorization header. Then passes the request to the next
+        # middleware in the stack.
+        #
+        # @param env [Faraday::Env] The request environment
+        # @return [Faraday::Response] The response from the next middleware
+        def call(env)
+          @token = @client.get_access_token_from_hash(@read_token.call)
+
+          if @token.expired? || @token.expires_at.nil?
+            @token = refresh_token!
+          end
+
+          env.request_headers["Authorization"] ||= "Bearer #{@token.token}"
+
+          @app.call(env)
+        end
+
+        private
+
+        # Refresh the expired OAuth token
+        #
+        # Uses the refresh token to obtain a new access token and stores it
+        # using the configured write_token proc. Converts OAuth2 errors to
+        # Booqable errors for consistent error handling.
+        #
+        # @return [OAuth2::AccessToken] The new access token
+        # @raise [Booqable::Error] For OAuth-related errors
+        def refresh_token!
+          new_token = @token.refresh!
+
+          @write_token.call(new_token.to_hash)
+
+          new_token
+        rescue OAuth2::Error => e
+          response = e.response.response.env.to_h
+
+          Booqable::Error.from_response(response)
+        end
+      end
+    end
+  end
+end

data/lib/booqable/middleware/auth/single_use.rb

@@ -0,0 +1,157 @@
+module Booqable
+  module Middleware
+    module Auth
+      # Faraday middleware for single-use JWT token authentication
+      #
+      # This middleware generates and adds single-use JWT tokens for authentication.
+      # Each token is unique per request and includes request-specific data like
+      # method, path, and body hash to prevent replay attacks.
+      #
+      # Supports multiple JWT algorithms: HS256 (HMAC), RS256 (RSA), and ES256 (ECDSA).
+      #
+      # For more info see: https://developers.booqable.com/#authentication-request-signing
+      #
+      # @example Adding to Faraday middleware stack
+      #   builder.use Booqable::Middleware::Auth::SingleUse,
+      #     single_use_token: "token_id",
+      #     single_use_token_algorithm: "HS256",
+      #     single_use_token_private_key: "secret_key",
+      #     single_use_token_company_id: "company_uuid",
+      #     single_use_token_user_id: "user_uuid",
+      #     api_endpoint: "https://company.booqable.com/api/4"
+      class SingleUse < Base
+        # Token kind identifier for JWT header
+        KIND = "single_use"
+
+        # Default domain for issuer URL construction
+        BOOQABLE_DOMAIN = "booqable.com"
+
+        # Initialize the single-use token authentication middleware
+        #
+        # @param app [#call] The next middleware in the Faraday stack
+        # @param options [Hash] Configuration options
+        # @option options [String] :single_use_token Token identifier (kid)
+        # @option options [String] :single_use_token_algorithm JWT algorithm (HS256, RS256, ES256)
+        # @option options [Integer] :single_use_token_expiration_period Token expiration in seconds (default: 600)
+        # @option options [String] :single_use_token_company_id Company UUID for audience claim
+        # @option options [String] :single_use_token_user_id User UUID for subject claim
+        # @option options [String] :single_use_token_private_key Private key or secret for signing
+        # @option options [String] :api_endpoint API endpoint URL for issuer determination
+        # @raise [SingleUseTokenAlgorithmRequired] If algorithm is not provided
+        # @raise [SingleUseTokenCompanyIdRequired] If company ID is not provided
+        # @raise [SingleUseTokenUserIdRequired] If user ID is not provided
+        # @raise [PrivateKeyOrSecretRequired] If private key/secret is not provided
+        def initialize(app, options = {})
+          super(app)
+
+          @kid = options.fetch(:single_use_token)
+          @alg = options.fetch(:single_use_token_algorithm) || raise(SingleUseTokenAlgorithmRequired)
+          @exp = options.fetch(:single_use_token_expiration_period, Time.now.to_i + 10 * 60)
+          @aud = options.fetch(:single_use_token_company_id) || raise(SingleUseTokenCompanyIdRequired)
+          @sub = options.fetch(:single_use_token_user_id) || raise(SingleUseTokenUserIdRequired)
+          @raw_private_key = options.fetch(:single_use_token_private_key) || raise(PrivateKeyOrSecretRequired)
+          @api_endpoint = options.fetch(:api_endpoint, nil)
+
+          @private_key = private_key
+        end
+
+        # Process the HTTP request and add single-use token authentication
+        #
+        # Generates a unique JWT token for this specific request and adds it
+        # to the Authorization header. Then passes the request to the next
+        # middleware in the stack.
+        #
+        # @param env [Faraday::Env] The request environment
+        # @return [Faraday::Response] The response from the next middleware
+        def call(env)
+          env.request_headers["Authorization"] ||= "Bearer #{generate_token(env)}"
+
+          @app.call(env)
+        end
+
+        private
+
+        # Generate a JWT token for the current request
+        #
+        # @param env [Faraday::Env] The request environment
+        # @return [String] Encoded JWT token
+        def generate_token(env)
+          JWT.encode generate_payload(env), @private_key, @alg, headers
+        end
+
+        # Generate the JWT payload with request-specific claims
+        #
+        # @param env [Faraday::Env] The request environment
+        # @return [Hash] JWT payload with standard and custom claims
+        def generate_payload(env)
+          data = generate_data(env)
+
+          request_id = SecureRandom.respond_to?(:uuid_v4) ? SecureRandom.uuid_v4 : SecureRandom.uuid
+
+          {
+            alg: @alg,
+            iat: Time.now.to_i,
+            exp: Time.now.to_i + @exp,
+            aud: @aud,
+            sub: @sub,
+            iss: iss,
+            jti: "#{request_id}.#{data}"
+          }
+        end
+
+        # Generate JWT headers
+        #
+        # @return [Hash] JWT headers with key ID and kind
+        def headers
+          { kid: @kid, kind: KIND }
+        end
+
+        # Generate request-specific data hash for the JWT
+        #
+        # Creates a hash from the HTTP method, full path, and body content
+        # to ensure each token is unique to the specific request being made.
+        #
+        # @param env [Faraday::Env] The request environment
+        # @return [String] Base64-encoded SHA256 hash of request data
+        def generate_data(env)
+          request_method = env.method.to_s.upcase
+          fullpath = env.url.request_uri
+          body = env.body
+          encoded_body = body ? Base64.strict_encode64(::OpenSSL::Digest::SHA256.new(body).digest) : nil
+
+          Base64.strict_encode64(
+            ::OpenSSL::Digest::SHA256.new([ request_method, fullpath, encoded_body ].join(".")).digest
+          )
+        end
+
+        # Generate the issuer URL for the JWT
+        #
+        # @return [String] Issuer URL based on the API endpoint
+        def iss
+          "https://#{slug}.#{BOOQABLE_DOMAIN}"
+        end
+
+        # Extract the company slug from the API endpoint
+        #
+        # @return [String] Company identifier from the hostname
+        def slug
+          Addressable::URI.parse(@api_endpoint).host.split(".").first
+        end
+
+        # Parse the private key based on the configured algorithm
+        #
+        # @return [OpenSSL::PKey::EC, OpenSSL::PKey::RSA, String] Parsed private key
+        def private_key
+          case @alg
+          when "ES256"
+            OpenSSL::PKey::EC.new(@raw_private_key)
+          when "RS256"
+            OpenSSL::PKey::RSA.new(@raw_private_key)
+          when "HS256"
+            @raw_private_key
+          end
+        end
+      end
+    end
+  end
+end

data/lib/booqable/middleware/base.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Booqable
+  module Middleware
+    Base = Faraday::Middleware
+  end
+end

data/lib/booqable/middleware/raise_error.rb

@@ -0,0 +1,29 @@
+module Booqable
+  # Faraday response middleware for the Booqable client
+  module Middleware
+    # Faraday middleware that raises Booqable exceptions based on HTTP status codes
+    #
+    # This middleware automatically converts HTTP error responses into appropriate
+    # Booqable exception classes. It inspects the response status code and body to
+    # determine the specific error type and raises the corresponding exception.
+    #
+    # @example Adding to Faraday middleware stack
+    #   builder.use Booqable::Middleware::RaiseError
+    #
+    # @see Booqable::Error.from_response
+    class RaiseError < Base
+      # Handle completed HTTP responses and raise exceptions for errors
+      #
+      # Called by Faraday after a response is received. Inspects the response
+      # and raises an appropriate Booqable exception if the status indicates an error.
+      # Successful responses are allowed to pass through unchanged.
+      #
+      # @param response [Faraday::Response] The HTTP response object
+      # @return [void]
+      # @raise [Booqable::Error] Various error subclasses based on status code
+      def on_complete(response)
+        Booqable::Error.from_response(response)
+      end
+    end
+  end
+end

data/lib/booqable/oauth_client.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "oauth2"
+
+module Booqable
+  # OAuth2 client for Booqable API authentication
+  #
+  # Provides OAuth2 authentication flow support for the Booqable API.
+  # Handles authorization code exchange for access tokens using the
+  # standard OAuth2 authorization code flow.
+  #
+  # @example Basic OAuth flow
+  #   oauth_client = Booqable::OAuthClient.new(
+  #     base_url: "https://demo.booqable.com",
+  #     client_id: "your_client_id",
+  #     client_secret: "your_client_secret",
+  #     redirect_uri: "https://yourapp.com/callback"
+  #   )
+  #
+  #   # After user authorizes and returns with code
+  #   token = oauth_client.get_token_from_code(params[:code])
+  #   access_token = token.token
+  class OAuthClient
+    # OAuth2 token endpoint path
+    TOKEN_ENDPOINT = "/oauth/token"
+
+    # Initialize a new OAuth client
+    #
+    # @param base_url [String] Base URL of the Booqable instance (e.g., "https://demo.booqable.com")
+    # @param client_id [String] OAuth2 client identifier
+    # @param client_secret [String] OAuth2 client secret
+    # @param redirect_uri [String] OAuth2 redirect URI for authorization callback
+    def initialize(api_endpoint:, client_id:, client_secret:, redirect_uri: nil)
+      @client = OAuth2::Client.new(
+        client_id,
+        client_secret,
+        site: api_endpoint,
+        token_url: api_endpoint + TOKEN_ENDPOINT,
+      )
+      @redirect_uri = redirect_uri
+    end
+
+    # Exchange an authorization code for an access token
+    #
+    # Exchanges the authorization code received from the OAuth callback
+    # for an access token that can be used to make API requests.
+    #
+    # @param code [String] Authorization code from OAuth callback
+    # @param scope [String] OAuth scope to request (default: "full_access")
+    # @return [OAuth2::AccessToken] Access token object with token and refresh token
+    # @raise [OAuth2::Error] If the authorization code is invalid or expired
+    #
+    # @example
+    #   token = oauth_client.get_token_from_code("auth_code_123")
+    #   access_token = token.token
+    #   refresh_token = token.refresh_token
+    def get_token_from_code(code, scope: "full_access")
+      @client.auth_code.get_token(code,
+                                  redirect_uri: @redirect_uri,
+                                  scope: scope,
+                                  grant_type: "authorization_code")
+    end
+
+    # Create an access token from a hash.
+    #
+    # @param hash [Hash] Hash containing access token data.
+    # @return [OAuth2::AccessToken] Access token object created from the hash.
+    def get_access_token_from_hash(hash)
+      OAuth2::AccessToken.from_hash(@client, hash)
+    end
+  end
+end

data/lib/booqable/rate_limit.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Booqable
+  # Rate limit information from API responses
+  #
+  # Contains rate limiting information extracted from HTTP response headers.
+  # This information is available when rate limit errors occur or can be
+  # accessed from successful responses to monitor API usage.
+  #
+  # @example Accessing rate limit info from an error
+  #   begin
+  #     Booqable.orders.list
+  #   rescue Booqable::TooManyRequests => e
+  #     rate_limit = e.context
+  #     puts "Rate limit: #{rate_limit.remaining}/#{rate_limit.limit}"
+  #     puts "Resets in: #{rate_limit.resets_in} seconds"
+  #   end
+  #
+  # @!attribute [w] limit
+  #   @return [Integer] Max tries per rate limit period
+  # @!attribute [w] remaining
+  #   @return [Integer] Remaining tries per rate limit period
+  # @!attribute [w] resets_in
+  #   @return [Integer] Number of seconds when rate limit resets
+  class RateLimit < Struct.new(:limit, :remaining, :resets_in)
+    # Extract rate limit information from HTTP response
+    #
+    # Parses standard rate limit headers from the HTTP response and creates
+    # a RateLimit object with the extracted information. Falls back to default
+    # values if headers are missing.
+    #
+    # @param response [#headers, #response_headers] HTTP response object
+    # @return [RateLimit] Rate limit information object
+    #
+    # @example
+    #   rate_limit = Booqable::RateLimit.from_response(response)
+    #   puts "#{rate_limit.remaining} requests remaining"
+    def self.from_response(response)
+      info = new
+      headers = response.headers if response.respond_to?(:headers) && !response.headers.nil?
+      headers ||= response.response_headers if response.respond_to?(:response_headers) && !response.response_headers.nil?
+      if headers
+        info.limit = (headers["X-RateLimit-Limit"] || 1).to_i
+        info.remaining = (headers["X-RateLimit-Remaining"] || 1).to_i
+        info.resets_in = (headers["X-RateLimit-Period"] || 1).to_i
+      end
+
+      info
+    end
+  end
+end

data/lib/booqable/resource_proxy.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Booqable
+  # Generic resource proxy for API collections
+  #
+  # Provides a uniform interface for interacting with API resources using
+  # standard CRUD operations. Each resource proxy handles the JSON:API
+  # formatting and delegates HTTP requests to the underlying client.
+  #
+  # @example Working with orders
+  #   orders = Booqable::ResourceProxy.new(client, "orders")
+  #
+  #   # Of course, you can also just use Booqable.orders directly.
+  #
+  #   # List all orders
+  #   all_orders = orders.list
+  #
+  #   # Find a specific order
+  #   order = orders.find("123")
+  #
+  #   # Create a new order
+  #   new_order = orders.create(starts_at: "2024-01-01T00:00:00Z", stops_at: "2024-01-02T00:00:00Z", status: "draft")
+  #
+  #   # Update an existing order
+  #   updated_order = orders.update("123", status: "reserved")
+  #
+  #   # Delete an existing order
+  #   orders.delete("123")
+  class ResourceProxy
+    # Initialize a new resource proxy
+    #
+    # @param client [Booqable::Client] The client instance to use for requests
+    # @param resource_name [String, Symbol] The name of the resource (e.g., "orders", "customers")
+    def initialize(client, resource_name)
+      @client = client
+      @resource = resource_name.to_s
+    end
+
+    # List all resources
+    #
+    # Retrieves a collection of resources with optional filtering and pagination.
+    # Uses the JSON:API specification for query parameters.
+    #
+    # @param params [Hash] Query parameters for filtering, sorting, and pagination
+    # @option params [String] :include Related resources to include (e.g., "customer,items")
+    # @option params [Hash] :filter Filter criteria (e.g., { status: "active" })
+    # @option params [String] :sort Sort criteria (e.g., "created_at", "-updated_at")
+    # @option params [Hash] :page Pagination parameters (e.g., { number: 1, size: 25 })
+    # @return [Array, Enumerator] Collection of resources or enumerator for auto-pagination
+    #
+    # @example List orders with filters
+    #   orders.list(
+    #     include: "customer",
+    #     filter: { status: "active" },
+    #     sort: "-created_at"
+    #   )
+    def list(params = {})
+      paginate @resource, params
+    end
+
+    # Find a specific resource by ID
+    #
+    # Retrieves a single resource by its unique identifier.
+    #
+    # @param id [String, Integer] The unique identifier of the resource
+    # @param params [Hash] Additional query parameters
+    # @option params [String] :include Related resources to include
+    # @return [Hash] The resource data
+    # @raise [Booqable::NotFound] If the resource doesn't exist
+    #
+    # @example Find an order by ID
+    #   order = orders.find("123", include: "customer,items")
+    def find(id, params = {})
+      response = request :get, "#{@resource}/#{id}", params
+      response.data
+    end
+
+    # Create a new resource
+    #
+    # Creates a new resource with the provided attributes using JSON:API format.
+    #
+    # @param attrs [Hash] Attributes for the new resource
+    # @return [Hash] The created resource data
+    # @raise [Booqable::UnprocessableEntity] If validation fails
+    #
+    # @example Create a new order
+    #   new_order = orders.create(
+    #     starts_at: "2024-01-01T00:00:00Z",
+    #     stops_at: "2024-01-02T00:00:00Z",
+    #     status: "draft"
+    #   )
+    def create(attrs = {})
+      response = request :post, @resource, { data: { type: @resource, attributes: attrs } }
+      response.data
+    end
+
+    # Update an existing resource
+    #
+    # Updates a resource with the provided attributes using JSON:API format.
+    #
+    # @param id [String, Integer] The unique identifier of the resource to update
+    # @param attrs [Hash] Attributes to update
+    # @return [Hash] The updated resource data
+    # @raise [Booqable::NotFound] If the resource doesn't exist
+    # @raise [Booqable::UnprocessableEntity] If validation fails
+    #
+    # @example Update an order
+    #   updated_order = orders.update("123", status: "reserved")
+    def update(id, attrs = {})
+      response = request :put, "#{@resource}/#{id}", { data: { type: @resource, id: id, attributes: attrs } }
+      response.data
+    end
+
+    # Delete an existing resource
+    #
+    # Deletes a resource by its unique identifier.
+    #
+    # @param id [String, Integer] The unique identifier of the resource to delete
+    # @return [Object] The deleted resource data
+    # @raise [Booqable::NotFound] If the resource doesn't exist
+    #
+    # @example Delete an order
+    #   deleted_order = orders.delete("123")
+    def delete(id)
+      response = request :delete, "#{@resource}/#{id}", {}
+      response.data
+    end
+
+    private
+
+    attr_reader :client
+
+    # Delegate request method to client
+    #
+    # @param args [Array] Arguments to pass to client.request
+    # @return [Object] Response from client.request
+    def request(...)
+      client.request(...)
+    end
+
+    # Delegate paginate method to client
+    #
+    # @param args [Array] Arguments to pass to client.paginate
+    # @return [Object] Response from client.paginate
+    def paginate(...)
+      client.paginate(...)
+    end
+  end
+end

data/lib/booqable/resources.json

@@ -0,0 +1,74 @@
+[
+  { "app_carriers": "carriers" },
+  { "app_subscriptions": "subscriptions" },
+  { "app_payment_options": "payment_options" },
+  "authentication_methods",
+  "barcodes",
+  "bundles",
+  "bundle_items",
+  "clusters",
+  "collections",
+  "collection_items",
+  "collection_trees",
+  "companies",
+  "countries",
+  "coupons",
+  "customers",
+  "default_properties",
+  "delivery_distance_calculations",
+  "deposit_holds",
+  "documents",
+  "emails",
+  "email_templates",
+  "employees",
+  "employee_invitations",
+  "inventory_breakdowns",
+  "inventory_levels",
+  "invoice_finalizations",
+  "invoice_revisions",
+  "item_prices",
+  "items",
+  "lines",
+  "line_charge_suggestions",
+  "locations",
+  "notes",
+  "orders",
+  "order_delivery_rate_recalculations",
+  "order_delivery_rates",
+  "order_fulfillments",
+  "order_price_recalculations",
+  "order_status_transitions",
+  "payments",
+  "payment_authorizations",
+  "payment_charges",
+  "payment_methods",
+  "payment_refunds",
+  "photos",
+  "plannings",
+  "price_rules",
+  "price_rulesets",
+  "price_structures",
+  "price_tiles",
+  "products",
+  "product_groups",
+  "properties",
+  "provinces",
+  "settings",
+  "signatures",
+  "sortings",
+  "stock_adjustments",
+  "stock_items",
+  "stock_item_archivations",
+  "stock_item_plannings",
+  "stock_item_suggestions",
+  "tags",
+  "tax_categories",
+  "tax_rates",
+  "tax_regions",
+  "tax_values",
+  "transfers",
+  "user_invitations",
+  "users",
+  "webhook_endpoints",
+  "webhooks"
+]