voltaria_sdk 2.34.5

data/lib/voltaria/investors/types/investor_list_repayments_request.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Investors
+    module Types
+      class InvestorListRepaymentsRequest < Internal::Types::Model
+        field :client_id, -> { String }, optional: true, nullable: false
+        field :loan_id, -> { String }, optional: true, nullable: false
+        field :installment_id, -> { String }, optional: true, nullable: false
+        field :page, -> { Integer }, optional: true, nullable: false
+        field :page_size, -> { Integer }, optional: true, nullable: false
+        field :order_by, -> { String }, optional: true, nullable: false
+        field :q, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/voltaria/loans/client.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Loans
+    class Client
+      # @param client [Voltaria::Internal::Http::RawClient]
+      #
+      # @return [void]
+      def initialize(client:)
+        @client = client
+      end
+
+      # Retrieve all loans associated with your partner account. Supports optional filtering by client ID.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [Integer, nil] :page
+      # @option params [Integer, nil] :page_size
+      # @option params [String, nil] :client_id
+      # @option params [String, nil] :order_by
+      # @option params [String, nil] :q
+      #
+      # @return [Voltaria::Types::PaginatedResponseLoanResponseWithClientInfo]
+      def list_loans(request_options: {}, **params)
+        params = Voltaria::Internal::Types::Utils.normalize_keys(params)
+        query_param_names = %i[page page_size client_id order_by q]
+        query_params = {}
+        query_params["page"] = params[:page] if params.key?(:page)
+        query_params["page_size"] = params[:page_size] if params.key?(:page_size)
+        query_params["client_id"] = params[:client_id] if params.key?(:client_id)
+        query_params["order_by"] = params[:order_by] if params.key?(:order_by)
+        query_params["q"] = params[:q] if params.key?(:q)
+        params.except(*query_param_names)
+
+        request = Voltaria::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "v2/loans",
+          query: query_params,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Voltaria::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Voltaria::Types::PaginatedResponseLoanResponseWithClientInfo.load(response.body)
+        else
+          error_class = Voltaria::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Create a new loan for an approved client with an active credit limit.
+      #
+      # @param request_options [Hash]
+      # @param params [Voltaria::Loans::Types::LoanCreatePayload]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @return [Voltaria::Types::LoanResponseWithInstallments]
+      def create_loan(request_options: {}, **params)
+        params = Voltaria::Internal::Types::Utils.normalize_keys(params)
+        request = Voltaria::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "v2/loans",
+          body: Voltaria::Loans::Types::LoanCreatePayload.new(params).to_h,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Voltaria::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Voltaria::Types::LoanResponseWithInstallments.load(response.body)
+        else
+          error_class = Voltaria::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Retrieve detailed information about a specific loan by its loan ID.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :loan_id
+      #
+      # @return [Voltaria::Types::LoanResponseWithInstallments]
+      def get_loan_by_id(request_options: {}, **params)
+        params = Voltaria::Internal::Types::Utils.normalize_keys(params)
+        request = Voltaria::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "v2/loans/#{URI.encode_uri_component(params[:loan_id].to_s)}",
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Voltaria::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Voltaria::Types::LoanResponseWithInstallments.load(response.body)
+        else
+          error_class = Voltaria::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Delete a loan by ID. Only loans with 'pending' status can be deleted.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :loan_id
+      #
+      # @return [Hash[String, Object], nil]
+      def delete_loan(request_options: {}, **params)
+        params = Voltaria::Internal::Types::Utils.normalize_keys(params)
+        request = Voltaria::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "DELETE",
+          path: "v2/loans/#{URI.encode_uri_component(params[:loan_id].to_s)}",
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Voltaria::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        return if code.between?(200, 299)
+
+        error_class = Voltaria::Errors::ResponseError.subclass_for_code(code)
+        raise error_class.new(response.body, code: code)
+      end
+
+      # Create multiple loans in a single request. Processing happens asynchronously. Returns a task ID for tracking
+      # progress.
+      #
+      # @param request_options [Hash]
+      # @param params [Voltaria::Loans::Types::BulkLoanCreatePayload]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @return [Voltaria::Types::BulkLoanTaskResponse]
+      def create_bulk_loans(request_options: {}, **params)
+        params = Voltaria::Internal::Types::Utils.normalize_keys(params)
+        request = Voltaria::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "v2/loans/bulk",
+          body: Voltaria::Loans::Types::BulkLoanCreatePayload.new(params).to_h,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Voltaria::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Voltaria::Types::BulkLoanTaskResponse.load(response.body)
+        else
+          error_class = Voltaria::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Check the status of a bulk loan creation task and retrieve results when completed.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :task_id
+      #
+      # @return [Voltaria::Types::BulkLoanTaskStatus]
+      def get_bulk_loan_status(request_options: {}, **params)
+        params = Voltaria::Internal::Types::Utils.normalize_keys(params)
+        request = Voltaria::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "v2/loans/bulk/#{URI.encode_uri_component(params[:task_id].to_s)}",
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Voltaria::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Voltaria::Types::BulkLoanTaskStatus.load(response.body)
+        else
+          error_class = Voltaria::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Mark a loan as defaulted, recording the default date and the amount recovered from selling it. Defaults the
+      # loan's active and overdue installments and updates the loan status accordingly.
+      #
+      # @param request_options [Hash]
+      # @param params [Voltaria::Loans::Types::LoanDefaultPayload]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :loan_id
+      #
+      # @return [Voltaria::Types::LoanResponseWithInstallments]
+      def set_loan_default(request_options: {}, **params)
+        params = Voltaria::Internal::Types::Utils.normalize_keys(params)
+        request_data = Voltaria::Loans::Types::LoanDefaultPayload.new(params).to_h
+        non_body_param_names = ["loan_id"]
+        body = request_data.except(*non_body_param_names)
+
+        request = Voltaria::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "v2/loans/#{URI.encode_uri_component(params[:loan_id].to_s)}/set-default",
+          body: body,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Voltaria::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Voltaria::Types::LoanResponseWithInstallments.load(response.body)
+        else
+          error_class = Voltaria::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+    end
+  end
+end

data/lib/voltaria/loans/types/bulk_loan_create_payload.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Loans
+    module Types
+      class BulkLoanCreatePayload < Internal::Types::Model
+        field :loans, -> { Internal::Types::Array[Voltaria::Types::BulkLoanItemPayload] }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/voltaria/loans/types/delete_loan_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Loans
+    module Types
+      class DeleteLoanRequest < Internal::Types::Model
+        field :loan_id, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/voltaria/loans/types/get_bulk_loan_status_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Loans
+    module Types
+      class GetBulkLoanStatusRequest < Internal::Types::Model
+        field :task_id, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/voltaria/loans/types/get_loan_by_id_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Loans
+    module Types
+      class GetLoanByIDRequest < Internal::Types::Model
+        field :loan_id, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/voltaria/loans/types/list_loans_request.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Loans
+    module Types
+      class ListLoansRequest < Internal::Types::Model
+        field :page, -> { Integer }, optional: true, nullable: false
+        field :page_size, -> { Integer }, optional: true, nullable: false
+        field :client_id, -> { String }, optional: true, nullable: false
+        field :order_by, -> { String }, optional: true, nullable: false
+        field :q, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/voltaria/loans/types/loan_create_payload.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Loans
+    module Types
+      class LoanCreatePayload < Internal::Types::Model
+        field :client_id, -> { String }, optional: false, nullable: false
+        field :currency, -> { Voltaria::Types::CurrencyEnum }, optional: false, nullable: false
+        field :amount, -> { Voltaria::Loans::Types::LoanCreatePayloadAmount }, optional: false, nullable: false
+        field :correlation_id, -> { String }, optional: true, nullable: false
+        field :loan_date, -> { String }, optional: true, nullable: false
+        field :installments, -> { Internal::Types::Array[Voltaria::Types::LoanInstallmentCreatePayload] }, optional: false, nullable: false
+        field :data, -> { Internal::Types::Hash[String, Object] }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/voltaria/loans/types/loan_create_payload_amount.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Loans
+    module Types
+      # The amount of the loan
+      class LoanCreatePayloadAmount < Internal::Types::Model
+        extend Voltaria::Internal::Types::Union
+
+        member -> { Integer }
+        member -> { String }
+      end
+    end
+  end
+end

data/lib/voltaria/loans/types/loan_default_payload.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Loans
+    module Types
+      class LoanDefaultPayload < Internal::Types::Model
+        field :loan_id, -> { String }, optional: false, nullable: false
+        field :default_date, -> { String }, optional: false, nullable: false
+        field :sold_amount, -> { Voltaria::Loans::Types::LoanDefaultPayloadSoldAmount }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/voltaria/loans/types/loan_default_payload_sold_amount.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Loans
+    module Types
+      # Amount recovered when the defaulted loan is sold.
+      class LoanDefaultPayloadSoldAmount < Internal::Types::Model
+        extend Voltaria::Internal::Types::Union
+
+        member -> { Integer }
+        member -> { String }
+      end
+    end
+  end
+end

data/lib/voltaria/partners/client.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Partners
+    class Client
+      # @param client [Voltaria::Internal::Http::RawClient]
+      #
+      # @return [void]
+      def initialize(client:)
+        @client = client
+      end
+
+      # Use this endpoint to check the available funding capacity in your dedicated lending account before initiating a
+      # new loan or submitting a drawdown request.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @return [Array[Voltaria::Types::AvailableFunding]]
+      def get_available_funding(request_options: {}, **params)
+        Voltaria::Internal::Types::Utils.normalize_keys(params)
+        request = Voltaria::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "v2/partners/available-funding",
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Voltaria::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          ::JSON.parse(response.body).map { |item| Voltaria::Types::AvailableFunding.load(::JSON.generate(item)) }
+        else
+          error_class = Voltaria::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Upload supplementary partner information, such as bank account balance, accounting figures, or other relevant
+      # details.
+      #
+      # @param request_options [Hash]
+      # @param params [Voltaria::Partners::Types::PartnerDataCreatePayload]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @return [Voltaria::Types::PartnerDataResponse]
+      def create_partner_data(request_options: {}, **params)
+        params = Voltaria::Internal::Types::Utils.normalize_keys(params)
+        request = Voltaria::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "v2/partners/data",
+          body: Voltaria::Partners::Types::PartnerDataCreatePayload.new(params).to_h,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Voltaria::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Voltaria::Types::PartnerDataResponse.load(response.body)
+        else
+          error_class = Voltaria::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Use this endpoint to get the list of waterfalls for your dedicated lending account.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [Integer, nil] :page
+      # @option params [Integer, nil] :page_size
+      # @option params [String, nil] :order_by
+      # @option params [String, nil] :q
+      #
+      # @return [Voltaria::Types::PaginatedResponseWaterfallResponse]
+      def list_partner_waterfalls(request_options: {}, **params)
+        params = Voltaria::Internal::Types::Utils.normalize_keys(params)
+        query_param_names = %i[page page_size order_by q]
+        query_params = {}
+        query_params["page"] = params[:page] if params.key?(:page)
+        query_params["page_size"] = params[:page_size] if params.key?(:page_size)
+        query_params["order_by"] = params[:order_by] if params.key?(:order_by)
+        query_params["q"] = params[:q] if params.key?(:q)
+        params.except(*query_param_names)
+
+        request = Voltaria::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "v2/partners/waterfalls",
+          query: query_params,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Voltaria::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Voltaria::Types::PaginatedResponseWaterfallResponse.load(response.body)
+        else
+          error_class = Voltaria::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+    end
+  end
+end

data/lib/voltaria/partners/types/list_partner_waterfalls_request.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Partners
+    module Types
+      class ListPartnerWaterfallsRequest < Internal::Types::Model
+        field :page, -> { Integer }, optional: true, nullable: false
+        field :page_size, -> { Integer }, optional: true, nullable: false
+        field :order_by, -> { String }, optional: true, nullable: false
+        field :q, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/voltaria/partners/types/partner_data_create_payload.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Partners
+    module Types
+      class PartnerDataCreatePayload < Internal::Types::Model
+        field :data, -> { Internal::Types::Hash[String, Object] }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/voltaria/prefix_routing.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Hand-written prefix-routing wrapper around the Fern-generated SDK.
+#
+# The generated client is `Voltaria::Client.new(token:, base_url:)`. This file
+# re-opens the `Voltaria` module to add a convenience factory that derives the
+# base URL from the API key prefix:
+#
+#   "live_"    -> Voltaria::Environment::PRODUCTION
+#   "sandbox_" -> Voltaria::Environment::SANDBOX
+#   unknown / empty -> raises Voltaria::InvalidApiKeyError
+#
+# An explicitly supplied :environment or :base_url ALWAYS overrides prefix
+# routing.
+#
+# This file is hand-written and must be listed in .fernignore so the generator
+# does not overwrite it.
+#
+# Consumers can opt in with a single require, which also loads the generated SDK:
+#
+#   require "voltaria/prefix_routing"
+#   client = Voltaria.new("live_abc123")
+
+require_relative "../voltaria"
+
+module Voltaria
+  # Raised when the API key prefix cannot be mapped to a known environment and
+  # no explicit environment / base_url was provided.
+  class InvalidApiKeyError < StandardError
+    def initialize(message = "API key must start with 'live_' or 'sandbox_', " \
+                             "or an explicit :environment / :base_url must be supplied")
+      super
+    end
+  end
+
+  # Prefix -> environment base URL mapping.
+  API_KEY_ENVIRONMENTS = {
+    "live_" => Voltaria::Environment::PRODUCTION,
+    "sandbox_" => Voltaria::Environment::SANDBOX
+  }.freeze
+
+  class << self
+    # Construct a Voltaria::Client, resolving the base URL from the API key
+    # prefix unless an explicit environment / base_url is given.
+    #
+    # @param api_key [String] the API key (e.g. "live_abc", "sandbox_abc")
+    # @param environment [String, nil] explicit base URL; overrides prefix routing
+    # @param base_url [String, nil] explicit base URL; overrides prefix routing
+    # @param options [Hash] forwarded to Voltaria::Client.new
+    #
+    # @return [Voltaria::Client]
+    def new(api_key, environment: nil, base_url: nil, **)
+      resolved = resolve_environment(api_key, environment: environment, base_url: base_url)
+      Voltaria::Client.new(token: api_key, base_url: base_url || resolved, **)
+    end
+
+    # Resolve the base URL to use.
+    #
+    # Mirrors the reference behavior exactly:
+    #   - explicit environment wins
+    #   - explicit base_url defers resolution to the caller (returns nil here)
+    #   - otherwise derive from the api_key prefix
+    #   - unknown / empty prefix raises InvalidApiKeyError
+    #
+    # @param api_key [String]
+    # @param environment [String, nil]
+    # @param base_url [String, nil]
+    #
+    # @return [String, nil]
+    def resolve_environment(api_key, environment: nil, base_url: nil)
+      return environment if environment
+      return nil if base_url
+
+      prefix = API_KEY_ENVIRONMENTS.keys.find { |p| api_key.to_s.start_with?(p) }
+      raise InvalidApiKeyError unless prefix
+
+      API_KEY_ENVIRONMENTS.fetch(prefix)
+    end
+  end
+end