buda_api 1.0.0

data/lib/buda_api/client.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+require "openssl"
+require "base64"
+require "time"
+
+module BudaApi
+  # Base client class providing core HTTP functionality and error handling
+  class Client
+    include Constants
+
+    attr_reader :base_url, :timeout, :retries, :debug_mode
+
+    DEFAULT_OPTIONS = {
+      base_url: "https://www.buda.com/api/v2/",
+      timeout: 30,
+      retries: 3,
+      debug_mode: false
+    }.freeze
+
+    def initialize(options = {})
+      @options = DEFAULT_OPTIONS.merge(options)
+      @base_url = @options[:base_url]
+      @timeout = @options[:timeout]
+      @retries = @options[:retries]
+      @debug_mode = @options[:debug_mode]
+
+      setup_logger
+      setup_http_client
+    end
+
+    protected
+
+    # Make a GET request
+    # @param path [String] API endpoint path
+    # @param params [Hash] query parameters
+    # @return [Hash] parsed response body
+    def get(path, params = {})
+      make_request(:get, path, params: params)
+    end
+
+    # Make a POST request  
+    # @param path [String] API endpoint path
+    # @param body [Hash] request body
+    # @param params [Hash] query parameters
+    # @return [Hash] parsed response body
+    def post(path, body: {}, params: {})
+      make_request(:post, path, body: body, params: params)
+    end
+
+    # Make a PUT request
+    # @param path [String] API endpoint path  
+    # @param body [Hash] request body
+    # @param params [Hash] query parameters
+    # @return [Hash] parsed response body
+    def put(path, body: {}, params: {})
+      make_request(:put, path, body: body, params: params)
+    end
+
+    # Make a DELETE request
+    # @param path [String] API endpoint path
+    # @param params [Hash] query parameters  
+    # @return [Hash] parsed response body
+    def delete(path, params = {})
+      make_request(:delete, path, params: params)
+    end
+
+    private
+
+    def setup_logger
+      log_level = @debug_mode ? :debug : BudaApi.configuration.logger_level
+      BudaApi::Logger.setup(level: log_level)
+    end
+
+    def setup_http_client
+      @http_client = Faraday.new(url: @base_url) do |f|
+        f.options.timeout = @timeout
+        f.options.open_timeout = @timeout / 2
+        
+        f.request :json
+        f.request :retry, 
+          max: @retries,
+          interval: 0.5,
+          backoff_factor: 2,
+          retry_statuses: [408, 429, 500, 502, 503, 504],
+          methods: [:get, :post, :put, :delete]
+
+        f.response :json, content_type: /\bjson$/
+        f.adapter :net_http
+      end
+    end
+
+    def make_request(method, path, body: nil, params: {}, headers: {})
+      start_time = Time.now
+      full_url = build_url(path, params)
+      
+      # Add authentication headers if this is an authenticated client
+      headers = add_authentication_headers(method, path, body, headers) if respond_to?(:add_authentication_headers, true)
+
+      BudaApi::Logger.log_request(method, full_url, headers: headers, body: body)
+
+      response = @http_client.public_send(method) do |req|
+        req.url path
+        req.params = params if params.any?
+        req.headers.merge!(headers)
+        req.body = body.to_json if body && !body.empty?
+      end
+
+      duration = ((Time.now - start_time) * 1000).round(2)
+      BudaApi::Logger.log_response(
+        response.status, 
+        headers: response.headers, 
+        body: response.body,
+        duration: duration
+      )
+
+      handle_response(response)
+
+    rescue Faraday::ConnectionFailed => e
+      error = ConnectionError.new("Connection failed: #{e.message}")
+      BudaApi::Logger.log_error(error, context: { method: method, path: path })
+      raise error
+
+    rescue Faraday::TimeoutError => e
+      error = TimeoutError.new("Request timed out: #{e.message}")
+      BudaApi::Logger.log_error(error, context: { method: method, path: path })
+      raise error
+
+    rescue StandardError => e
+      error = ApiError.new("Unexpected error: #{e.message}")
+      BudaApi::Logger.log_error(error, context: { method: method, path: path })
+      raise error
+    end
+
+    def build_url(path, params)
+      url = @base_url + path.to_s
+      return url if params.empty?
+
+      query_string = params.map { |k, v| "#{k}=#{v}" }.join("&")
+      "#{url}?#{query_string}"
+    end
+
+    def handle_response(response)
+      case response.status
+      when HttpStatus::OK, HttpStatus::CREATED
+        validate_and_parse_response(response)
+      when HttpStatus::BAD_REQUEST
+        handle_error_response(BadRequestError, response, "Bad request")
+      when HttpStatus::UNAUTHORIZED
+        handle_error_response(AuthenticationError, response, "Authentication failed")
+      when HttpStatus::FORBIDDEN  
+        handle_error_response(AuthorizationError, response, "Forbidden - insufficient permissions")
+      when HttpStatus::NOT_FOUND
+        handle_error_response(NotFoundError, response, "Resource not found")
+      when HttpStatus::UNPROCESSABLE_ENTITY
+        handle_error_response(ValidationError, response, "Validation failed")
+      when HttpStatus::RATE_LIMITED
+        handle_error_response(RateLimitError, response, "Rate limit exceeded")
+      when HttpStatus::INTERNAL_SERVER_ERROR..HttpStatus::GATEWAY_TIMEOUT
+        handle_error_response(ServerError, response, "Server error")
+      else
+        handle_error_response(ApiError, response, "Unknown error")
+      end
+    end
+
+    def validate_and_parse_response(response)
+      body = response.body
+
+      if body.nil? || body.empty?
+        raise InvalidResponseError.new("Empty response body", status_code: response.status)
+      end
+
+      unless body.is_a?(Hash)
+        raise InvalidResponseError.new("Invalid response format", 
+                                     status_code: response.status, 
+                                     response_body: body)
+      end
+
+      # Check for API error in successful HTTP response
+      if body.key?("message") && body["message"]&.match?(/error/i)
+        raise ApiError.new(body["message"], 
+                          status_code: response.status, 
+                          response_body: body)
+      end
+
+      body
+    end
+
+    def handle_error_response(error_class, response, default_message)
+      error_message = extract_error_message(response.body) || default_message
+
+      raise error_class.new(
+        error_message,
+        status_code: response.status,
+        response_body: response.body,
+        response_headers: response.headers.to_h
+      )
+    end
+
+    def extract_error_message(body)
+      return nil unless body.is_a?(Hash)
+
+      # Try different common error message fields
+      %w[message error error_message detail details].each do |field|
+        return body[field] if body[field].is_a?(String) && !body[field].empty?
+      end
+
+      # Handle nested error structures
+      if body["errors"].is_a?(Array) && body["errors"].any?
+        return body["errors"].first if body["errors"].first.is_a?(String)
+        return body["errors"].first["message"] if body["errors"].first.is_a?(Hash)
+      end
+
+      nil
+    end
+
+    # Validate required parameters
+    def validate_required_params(params, required_fields)
+      missing = required_fields.select { |field| params[field].nil? || params[field].to_s.empty? }
+      return if missing.empty?
+
+      raise ValidationError, "Missing required parameters: #{missing.join(', ')}"
+    end
+
+    # Validate parameter values against allowed options
+    def validate_param_values(params, validations)
+      validations.each do |param, allowed_values|
+        value = params[param]
+        next if value.nil?
+
+        unless allowed_values.include?(value)
+          raise ValidationError, 
+                "Invalid #{param}: '#{value}'. Must be one of: #{allowed_values.join(', ')}"
+        end
+      end
+    end
+
+    # Clean and normalize parameters
+    def normalize_params(params)
+      params.reject { |_, v| v.nil? || v.to_s.empty? }
+             .transform_keys(&:to_s)
+             .transform_values { |v| v.is_a?(Symbol) ? v.to_s : v }
+    end
+  end
+end

data/lib/buda_api/constants.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module BudaApi
+  # Constants and enums for the Buda API
+  module Constants
+    # Supported currencies
+    module Currency
+      ARS = "ARS"    # Argentine Peso
+      BCH = "BCH"    # Bitcoin Cash
+      BTC = "BTC"    # Bitcoin
+      CLP = "CLP"    # Chilean Peso  
+      COP = "COP"    # Colombian Peso
+      ETH = "ETH"    # Ethereum
+      LTC = "LTC"    # Litecoin
+      PEN = "PEN"    # Peruvian Sol
+      USDC = "USDC"  # USD Coin
+
+      ALL = [ARS, BCH, BTC, CLP, COP, ETH, LTC, PEN, USDC].freeze
+
+      # Currency decimal places
+      DECIMALS = {
+        ARS => 2,
+        BCH => 8,
+        BTC => 8,
+        CLP => 2,
+        COP => 2,
+        ETH => 9,
+        LTC => 8,
+        PEN => 2,
+        USDC => 2
+      }.freeze
+    end
+
+    # Supported trading pairs
+    module Market
+      # Bitcoin pairs
+      BTC_ARS = "BTC-ARS"
+      BTC_CLP = "BTC-CLP"
+      BTC_COP = "BTC-COP"
+      BTC_PEN = "BTC-PEN"
+      BTC_USDC = "BTC-USDC"
+
+      # Ethereum pairs
+      ETH_ARS = "ETH-ARS"
+      ETH_BTC = "ETH-BTC"
+      ETH_CLP = "ETH-CLP" 
+      ETH_COP = "ETH-COP"
+      ETH_PEN = "ETH-PEN"
+
+      # Bitcoin Cash pairs
+      BCH_ARS = "BCH-ARS"
+      BCH_BTC = "BCH-BTC"
+      BCH_CLP = "BCH-CLP"
+      BCH_COP = "BCH-COP"
+      BCH_PEN = "BCH-PEN"
+
+      # Litecoin pairs
+      LTC_ARS = "LTC-ARS"
+      LTC_BTC = "LTC-BTC"
+      LTC_CLP = "LTC-CLP"
+      LTC_COP = "LTC-COP"
+      LTC_PEN = "LTC-PEN"
+
+      # USDC pairs
+      USDC_ARS = "USDC-ARS"
+      USDC_CLP = "USDC-CLP"
+      USDC_COP = "USDC-COP"
+      USDC_PEN = "USDC-PEN"
+
+      ALL = [
+        BTC_ARS, BTC_CLP, BTC_COP, BTC_PEN, BTC_USDC,
+        ETH_ARS, ETH_BTC, ETH_CLP, ETH_COP, ETH_PEN,
+        BCH_ARS, BCH_BTC, BCH_CLP, BCH_COP, BCH_PEN,
+        LTC_ARS, LTC_BTC, LTC_CLP, LTC_COP, LTC_PEN,
+        USDC_ARS, USDC_CLP, USDC_COP, USDC_PEN
+      ].freeze
+    end
+
+    # Order types
+    module OrderType
+      ASK = "Ask"    # Sell order
+      BID = "Bid"    # Buy order
+
+      ALL = [ASK, BID].freeze
+    end
+
+    # Price types for orders
+    module PriceType
+      MARKET = "market"
+      LIMIT = "limit"
+
+      ALL = [MARKET, LIMIT].freeze
+    end
+
+    # Order states
+    module OrderState
+      RECEIVED = "received"
+      PENDING = "pending"
+      TRADED = "traded"
+      CANCELING = "canceling"
+      CANCELED = "canceled"
+
+      ALL = [RECEIVED, PENDING, TRADED, CANCELING, CANCELED].freeze
+    end
+
+    # Quotation types
+    module QuotationType
+      BID_GIVEN_SIZE = "bid_given_size"
+      BID_GIVEN_EARNED_BASE = "bid_given_earned_base"
+      BID_GIVEN_SPENT_QUOTE = "bid_given_spent_quote"
+      ASK_GIVEN_SIZE = "ask_given_size"
+      ASK_GIVEN_EARNED_QUOTE = "ask_given_earned_quote"
+      ASK_GIVEN_SPENT_BASE = "ask_given_spent_base"
+
+      ALL = [
+        BID_GIVEN_SIZE, BID_GIVEN_EARNED_BASE, BID_GIVEN_SPENT_QUOTE,
+        ASK_GIVEN_SIZE, ASK_GIVEN_EARNED_QUOTE, ASK_GIVEN_SPENT_BASE
+      ].freeze
+    end
+
+    # Balance event types
+    module BalanceEvent
+      DEPOSIT_CONFIRM = "deposit_confirm"
+      WITHDRAWAL_CONFIRM = "withdrawal_confirm" 
+      TRANSACTION = "transaction"
+      TRANSFER_CONFIRMATION = "transfer_confirmation"
+
+      ALL = [DEPOSIT_CONFIRM, WITHDRAWAL_CONFIRM, TRANSACTION, TRANSFER_CONFIRMATION].freeze
+    end
+
+    # Report types
+    module ReportType
+      AVERAGE_PRICES = "average_prices"
+      CANDLESTICK = "candlestick"
+
+      ALL = [AVERAGE_PRICES, CANDLESTICK].freeze
+    end
+
+    # API limits
+    module Limits
+      ORDERS_PER_PAGE = 300
+      TRANSFERS_PER_PAGE = 300
+      DEFAULT_TIMEOUT = 30
+      MAX_RETRIES = 3
+    end
+
+    # HTTP status codes
+    module HttpStatus
+      OK = 200
+      CREATED = 201
+      BAD_REQUEST = 400
+      UNAUTHORIZED = 401
+      FORBIDDEN = 403
+      NOT_FOUND = 404
+      UNPROCESSABLE_ENTITY = 422
+      RATE_LIMITED = 429
+      INTERNAL_SERVER_ERROR = 500
+      BAD_GATEWAY = 502
+      SERVICE_UNAVAILABLE = 503
+      GATEWAY_TIMEOUT = 504
+    end
+  end
+end

data/lib/buda_api/errors.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module BudaApi
+  # Custom error classes for the Buda API SDK
+  module Errors
+    # Base error class for all API errors
+    class ApiError < StandardError
+      attr_reader :status_code, :response_body, :response_headers
+
+      def initialize(message, status_code: nil, response_body: nil, response_headers: nil)
+        super(message)
+        @status_code = status_code
+        @response_body = response_body
+        @response_headers = response_headers
+      end
+
+      def to_s
+        msg = super
+        msg += " (HTTP #{@status_code})" if @status_code
+        msg
+      end
+    end
+
+    # Authentication related errors
+    class AuthenticationError < ApiError; end
+
+    # Authorization/permission related errors  
+    class AuthorizationError < ApiError; end
+
+    # Rate limiting errors
+    class RateLimitError < ApiError; end
+
+    # Invalid request errors (4xx)
+    class BadRequestError < ApiError; end
+
+    # Resource not found errors
+    class NotFoundError < ApiError; end
+
+    # Server errors (5xx)
+    class ServerError < ApiError; end
+
+    # Network/connection related errors
+    class ConnectionError < ApiError; end
+
+    # Request timeout errors
+    class TimeoutError < ApiError; end
+
+    # Invalid response format errors
+    class InvalidResponseError < ApiError; end
+
+    # Configuration errors
+    class ConfigurationError < StandardError; end
+
+    # Validation errors for request parameters
+    class ValidationError < StandardError; end
+  end
+
+  # Include all error classes at the module level for convenience
+  include Errors
+end

data/lib/buda_api/logger.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module BudaApi
+  # Centralized logging functionality for the SDK
+  class Logger
+    LOG_LEVELS = {
+      debug: ::Logger::DEBUG,
+      info: ::Logger::INFO,
+      warn: ::Logger::WARN,
+      error: ::Logger::ERROR,
+      fatal: ::Logger::FATAL
+    }.freeze
+
+    class << self
+      attr_accessor :logger
+
+      # Initialize the logger
+      def setup(level: :info, output: $stdout)
+        @logger = ::Logger.new(output)
+        @logger.level = LOG_LEVELS[level] || LOG_LEVELS[:info]
+        @logger.formatter = proc do |severity, datetime, progname, msg|
+          "[#{datetime.strftime('%Y-%m-%d %H:%M:%S')}] #{severity.ljust(5)} BudaApi: #{msg}\n"
+        end
+        @logger
+      end
+
+      # Log debug messages
+      def debug(message)
+        current_logger.debug(message)
+      end
+
+      # Log info messages
+      def info(message)
+        current_logger.info(message)
+      end
+
+      # Log warning messages  
+      def warn(message)
+        current_logger.warn(message)
+      end
+
+      # Log error messages
+      def error(message)
+        current_logger.error(message)
+      end
+
+      # Log fatal messages
+      def fatal(message)
+        current_logger.fatal(message)
+      end
+
+      # Log HTTP requests in debug mode
+      def log_request(method, url, headers: {}, body: nil)
+        return unless debug_enabled?
+
+        debug("→ #{method.upcase} #{url}")
+        debug("→ Headers: #{headers}") if headers&.any?
+        debug("→ Body: #{body}") if body
+      end
+
+      # Log HTTP responses in debug mode
+      def log_response(status, headers: {}, body: nil, duration: nil)
+        return unless debug_enabled?
+
+        debug("← #{status}")
+        debug("← Headers: #{headers}") if headers&.any?
+        debug("← Body: #{truncate_body(body)}") if body
+        debug("← Duration: #{duration}ms") if duration
+      end
+
+      # Log errors with full context
+      def log_error(error, context: {})
+        error_msg = "Error: #{error.class.name} - #{error.message}"
+        error_msg += "\nContext: #{context}" if context&.any?
+        error_msg += "\nBacktrace:\n  #{error.backtrace.join("\n  ")}" if error.backtrace
+
+        error(error_msg)
+      end
+
+      private
+
+      def current_logger
+        @logger || setup
+      end
+
+      def debug_enabled?
+        current_logger.level <= ::Logger::DEBUG
+      end
+
+      def truncate_body(body, limit: 1000)
+        return body unless body.is_a?(String) && body.length > limit
+
+        "#{body[0...limit]}... (truncated)"
+      end
+    end
+  end
+end