buda_api 1.0.0

data/lib/buda_api/models.rb

@@ -0,0 +1,365 @@
+# frozen_string_literal: true
+
+require "ostruct"
+require "time"
+
+module BudaApi
+  # Data models for API responses
+  module Models
+    # Base model class with common functionality
+    class BaseModel
+      def initialize(data = {})
+        @data = data.is_a?(Hash) ? data : {}
+        @raw_data = @data.dup
+      end
+
+      # Access to raw API response data
+      def raw
+        @raw_data
+      end
+
+      # Convert to hash
+      def to_h
+        @data
+      end
+
+      # Convert to JSON  
+      def to_json(*args)
+        @data.to_json(*args)
+      end
+
+      private
+
+      def parse_datetime(datetime_string)
+        return nil if datetime_string.nil? || datetime_string.empty?
+        
+        Time.parse(datetime_string)
+      rescue ArgumentError
+        nil
+      end
+
+      def parse_amount(amount_data)
+        return nil unless amount_data.is_a?(Hash)
+        
+        Amount.new(amount_data)
+      end
+    end
+
+    # Amount model for currency amounts
+    class Amount < BaseModel
+      def initialize(data)
+        super(data)
+        @amount = data["amount"]&.to_f || 0.0
+        @currency = data["currency"]
+      end
+
+      attr_reader :amount, :currency
+
+      def to_s
+        "#{@amount} #{@currency}"
+      end
+
+      def ==(other)
+        other.is_a?(Amount) && 
+        @amount == other.amount && 
+        @currency == other.currency
+      end
+    end
+
+    # Market model
+    class Market < BaseModel
+      def initialize(data)
+        super(data)
+        @id = data["id"]
+        @name = data["name"] 
+        @base_currency = data["base_currency"]
+        @quote_currency = data["quote_currency"]
+        @minimum_order_amount = parse_amount(data["minimum_order_amount"])
+      end
+
+      attr_reader :id, :name, :base_currency, :quote_currency, :minimum_order_amount
+    end
+
+    # Ticker model
+    class Ticker < BaseModel  
+      def initialize(data)
+        super(data)
+        @last_price = parse_amount(data["last_price"])
+        @min_ask = parse_amount(data["min_ask"])
+        @max_bid = parse_amount(data["max_bid"])
+        @volume = parse_amount(data["volume"])
+        @price_variation_24h = data["price_variation_24h"]&.to_f
+        @price_variation_7d = data["price_variation_7d"]&.to_f
+      end
+
+      attr_reader :last_price, :min_ask, :max_bid, :volume, 
+                  :price_variation_24h, :price_variation_7d
+    end
+
+    # Order book entry model
+    class OrderBookEntry < BaseModel
+      def initialize(data)
+        super(data)
+        if data.is_a?(Array) && data.length >= 2
+          @price = data[0].to_f
+          @amount = data[1].to_f
+        else
+          @price = data["price"]&.to_f || 0.0
+          @amount = data["amount"]&.to_f || 0.0
+        end
+      end
+
+      attr_reader :price, :amount
+
+      def total
+        @price * @amount
+      end
+    end
+
+    # Order book model
+    class OrderBook < BaseModel
+      def initialize(data)
+        super(data)
+        @asks = (data["asks"] || []).map { |entry| OrderBookEntry.new(entry) }
+        @bids = (data["bids"] || []).map { |entry| OrderBookEntry.new(entry) }
+      end
+
+      attr_reader :asks, :bids
+
+      def best_ask
+        @asks.first
+      end
+
+      def best_bid
+        @bids.first
+      end
+
+      def spread
+        return nil unless best_ask && best_bid
+        
+        best_ask.price - best_bid.price
+      end
+
+      def spread_percentage
+        return nil unless best_ask && best_bid && best_bid.price > 0
+        
+        ((best_ask.price - best_bid.price) / best_bid.price * 100).round(4)
+      end
+    end
+
+    # Trade model
+    class Trade < BaseModel
+      def initialize(data)
+        super(data)
+        @timestamp = parse_datetime(data["timestamp"]) || Time.at(data["timestamp"].to_i) if data["timestamp"]
+        @direction = data["direction"]
+        @price = parse_amount(data["price"])
+        @amount = parse_amount(data["amount"])
+        @market_id = data["market_id"]
+      end
+
+      attr_reader :timestamp, :direction, :price, :amount, :market_id
+    end
+
+    # Trades collection model
+    class Trades < BaseModel
+      def initialize(data)
+        super(data) 
+        @trades = (data["trades"] || []).map { |trade_data| Trade.new(trade_data) }
+        @last_timestamp = data["last_timestamp"]
+      end
+
+      attr_reader :trades, :last_timestamp
+
+      def count
+        @trades.length
+      end
+
+      def each(&block)
+        @trades.each(&block)
+      end
+    end
+
+    # Balance model
+    class Balance < BaseModel
+      def initialize(data)
+        super(data)
+        @id = data["id"] 
+        @account_id = data["account_id"]
+        @amount = parse_amount(data["amount"])
+        @available_amount = parse_amount(data["available_amount"])
+        @frozen_amount = parse_amount(data["frozen_amount"])
+        @pending_withdraw_amount = parse_amount(data["pending_withdraw_amount"])
+      end
+
+      attr_reader :id, :account_id, :amount, :available_amount, 
+                  :frozen_amount, :pending_withdraw_amount
+
+      def currency
+        @amount&.currency
+      end
+    end
+
+    # Order model
+    class Order < BaseModel
+      def initialize(data)
+        super(data)
+        @id = data["id"]
+        @account_id = data["account_id"]
+        @amount = parse_amount(data["amount"])
+        @created_at = parse_datetime(data["created_at"])
+        @fee_currency = data["fee_currency"]
+        @limit = parse_amount(data["limit"])
+        @market_id = data["market_id"]
+        @original_amount = parse_amount(data["original_amount"])
+        @paid_fee = parse_amount(data["paid_fee"])
+        @price_type = data["price_type"]
+        @state = data["state"]
+        @total_exchanged = parse_amount(data["total_exchanged"])
+        @traded_amount = parse_amount(data["traded_amount"])
+        @type = data["type"]
+      end
+
+      attr_reader :id, :account_id, :amount, :created_at, :fee_currency,
+                  :limit, :market_id, :original_amount, :paid_fee, :price_type,
+                  :state, :total_exchanged, :traded_amount, :type
+
+      def filled_percentage
+        return 0 unless @original_amount&.amount && @original_amount.amount > 0
+        
+        ((@traded_amount&.amount || 0) / @original_amount.amount * 100).round(2)
+      end
+
+      def is_filled?
+        @state == "traded"
+      end
+
+      def is_active?
+        %w[received pending].include?(@state)
+      end
+
+      def is_cancelled?
+        %w[canceled canceling].include?(@state)
+      end
+    end
+
+    # Quotation model  
+    class Quotation < BaseModel
+      def initialize(data)
+        super(data)
+        @type = data["type"]
+        @reverse_amount = parse_amount(data["reverse_amount"])
+        @amount = parse_amount(data["amount"])
+        @base_balance_change = parse_amount(data["base_balance_change"])
+        @quote_balance_change = parse_amount(data["quote_balance_change"])
+        @fee = parse_amount(data["fee"])
+      end
+
+      attr_reader :type, :reverse_amount, :amount, :base_balance_change,
+                  :quote_balance_change, :fee
+    end
+
+    # Withdrawal model
+    class Withdrawal < BaseModel
+      def initialize(data)
+        super(data)
+        @id = data["id"]
+        @created_at = parse_datetime(data["created_at"])
+        @amount = parse_amount(data["amount"])
+        @fee = parse_amount(data["fee"])
+        @currency = data["currency"]
+        @state = data["state"]
+        @withdrawal_data = data["withdrawal_data"]
+      end
+
+      attr_reader :id, :created_at, :amount, :fee, :currency, :state, :withdrawal_data
+
+      def target_address
+        @withdrawal_data&.dig("target_address")
+      end
+    end
+
+    # Deposit model  
+    class Deposit < BaseModel
+      def initialize(data)
+        super(data)
+        @id = data["id"]
+        @created_at = parse_datetime(data["created_at"])
+        @amount = parse_amount(data["amount"])
+        @currency = data["currency"]
+        @state = data["state"]
+        @deposit_data = data["deposit_data"]
+      end
+
+      attr_reader :id, :created_at, :amount, :currency, :state, :deposit_data
+
+      def address
+        @deposit_data&.dig("address")
+      end
+    end
+
+    # Pagination metadata
+    class PaginationMeta < BaseModel
+      def initialize(data)
+        super(data)
+        @current_page = data["current_page"]&.to_i
+        @total_count = data["total_count"]&.to_i
+        @total_pages = data["total_pages"]&.to_i
+      end
+
+      attr_reader :current_page, :total_count, :total_pages
+
+      def has_next_page?
+        @current_page && @total_pages && @current_page < @total_pages
+      end
+
+      def has_previous_page?
+        @current_page && @current_page > 1
+      end
+    end
+
+    # Paginated collection of orders
+    class OrderPages < BaseModel
+      def initialize(orders_data, meta_data)
+        @orders = orders_data.map { |order| Order.new(order) }
+        @meta = PaginationMeta.new(meta_data || {})
+      end
+
+      attr_reader :orders, :meta
+
+      def count
+        @orders.length
+      end
+
+      def each(&block)
+        @orders.each(&block)
+      end
+    end
+
+    # Average price report entry
+    class AveragePrice < BaseModel
+      def initialize(data)
+        super(data)
+        @timestamp = Time.at(data["timestamp"].to_i) if data["timestamp"]
+        @average = data["average"]&.to_f
+      end
+
+      attr_reader :timestamp, :average
+    end
+
+    # Candlestick report entry  
+    class Candlestick < BaseModel
+      def initialize(data)
+        super(data)
+        @timestamp = Time.at(data["timestamp"].to_i) if data["timestamp"]
+        @open = data["open"]&.to_f
+        @close = data["close"]&.to_f
+        @high = data["high"]&.to_f  
+        @low = data["low"]&.to_f
+        @volume = data["volume"]&.to_f
+      end
+
+      attr_reader :timestamp, :open, :close, :high, :low, :volume
+    end
+  end
+end

data/lib/buda_api/public_client.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module BudaApi
+  # Public API client for endpoints that don't require authentication
+  class PublicClient < Client
+    include Models
+
+    # Get all available markets
+    #
+    # @return [Array<Market>] list of available markets
+    # @example
+    #   client = BudaApi::PublicClient.new
+    #   markets = client.markets
+    #   markets.each { |market| puts "#{market.id}: #{market.name}" }
+    def markets
+      BudaApi::Logger.info("Fetching all markets")
+      
+      response = get("markets")
+      markets_data = response["markets"] || []
+      
+      markets = markets_data.map { |market_data| Market.new(market_data) }
+      BudaApi::Logger.info("Retrieved #{markets.length} markets")
+      
+      markets
+    end
+
+    # Get details for a specific market
+    #
+    # @param market_id [String] market identifier (e.g., "BTC-CLP")
+    # @return [Market] market details
+    # @example
+    #   client = BudaApi::PublicClient.new
+    #   market = client.market_details("BTC-CLP")
+    #   puts "Minimum order: #{market.minimum_order_amount}"
+    def market_details(market_id)
+      validate_required_params({ market_id: market_id }, [:market_id])
+      validate_param_values({ market_id: market_id }, { market_id: Market::ALL })
+
+      BudaApi::Logger.info("Fetching market details for #{market_id}")
+      
+      response = get("markets/#{market_id}")
+      Market.new(response["market"])
+    end
+
+    # Get ticker information for a market
+    #
+    # @param market_id [String] market identifier
+    # @return [Ticker] current ticker information
+    # @example
+    #   client = BudaApi::PublicClient.new  
+    #   ticker = client.ticker("BTC-CLP")
+    #   puts "Last price: #{ticker.last_price}"
+    #   puts "24h change: #{ticker.price_variation_24h}%"
+    def ticker(market_id)
+      validate_required_params({ market_id: market_id }, [:market_id])
+      validate_param_values({ market_id: market_id }, { market_id: Market::ALL })
+
+      BudaApi::Logger.info("Fetching ticker for #{market_id}")
+      
+      response = get("markets/#{market_id}/ticker")
+      Ticker.new(response["ticker"])
+    end
+
+    # Get order book for a market
+    #
+    # @param market_id [String] market identifier
+    # @return [OrderBook] current order book
+    # @example
+    #   client = BudaApi::PublicClient.new
+    #   order_book = client.order_book("BTC-CLP") 
+    #   puts "Best ask: #{order_book.best_ask.price}"
+    #   puts "Best bid: #{order_book.best_bid.price}"
+    #   puts "Spread: #{order_book.spread_percentage}%"
+    def order_book(market_id)
+      validate_required_params({ market_id: market_id }, [:market_id])
+      validate_param_values({ market_id: market_id }, { market_id: Market::ALL })
+
+      BudaApi::Logger.info("Fetching order book for #{market_id}")
+      
+      response = get("markets/#{market_id}/order_book")
+      OrderBook.new(response["order_book"])
+    end
+
+    # Get recent trades for a market
+    #
+    # @param market_id [String] market identifier  
+    # @param timestamp [Integer, nil] trades after this timestamp
+    # @param limit [Integer, nil] maximum number of trades to return
+    # @return [Trades] collection of recent trades
+    # @example
+    #   client = BudaApi::PublicClient.new
+    #   trades = client.trades("BTC-CLP", limit: 10)
+    #   trades.each { |trade| puts "#{trade.amount} at #{trade.price}" }
+    def trades(market_id, timestamp: nil, limit: nil)
+      validate_required_params({ market_id: market_id }, [:market_id])
+      validate_param_values({ market_id: market_id }, { market_id: Market::ALL })
+
+      params = normalize_params({
+        timestamp: timestamp,
+        limit: limit
+      })
+
+      BudaApi::Logger.info("Fetching trades for #{market_id} with params: #{params}")
+      
+      response = get("markets/#{market_id}/trades", params)
+      Trades.new(response["trades"])
+    end
+
+    # Get a quotation for a potential trade
+    #
+    # @param market_id [String] market identifier
+    # @param quotation_type [String] type of quotation
+    # @param amount [Float] amount for quotation
+    # @param limit [Float, nil] limit price for limit quotations
+    # @return [Quotation] quotation details
+    # @example
+    #   client = BudaApi::PublicClient.new
+    #   # Get quotation for buying 0.1 BTC at market price
+    #   quote = client.quotation("BTC-CLP", "bid_given_size", 0.1)
+    #   puts "You would pay: #{quote.quote_balance_change}"
+    def quotation(market_id, quotation_type, amount, limit: nil)
+      validate_required_params({ 
+        market_id: market_id, 
+        quotation_type: quotation_type, 
+        amount: amount 
+      }, [:market_id, :quotation_type, :amount])
+      
+      validate_param_values({ 
+        market_id: market_id,
+        quotation_type: quotation_type 
+      }, { 
+        market_id: Market::ALL,
+        quotation_type: QuotationType::ALL 
+      })
+
+      quotation_payload = {
+        type: quotation_type,
+        amount: amount.to_s
+      }
+      quotation_payload[:limit] = limit.to_s if limit
+
+      BudaApi::Logger.info("Getting quotation for #{market_id}: #{quotation_type} #{amount}")
+      
+      response = post("markets/#{market_id}/quotations", body: { quotation: quotation_payload })
+      Quotation.new(response["quotation"])
+    end
+
+    # Get a market quotation (no limit price)
+    #
+    # @param market_id [String] market identifier
+    # @param quotation_type [String] type of quotation
+    # @param amount [Float] amount for quotation 
+    # @return [Quotation] market quotation details
+    def quotation_market(market_id, quotation_type, amount)
+      quotation(market_id, quotation_type, amount)
+    end
+
+    # Get a limit quotation (with limit price)
+    #
+    # @param market_id [String] market identifier
+    # @param quotation_type [String] type of quotation
+    # @param amount [Float] amount for quotation
+    # @param limit [Float] limit price
+    # @return [Quotation] limit quotation details
+    def quotation_limit(market_id, quotation_type, amount, limit)
+      quotation(market_id, quotation_type, amount, limit: limit)
+    end
+
+    # Get average prices report
+    #
+    # @param market_id [String] market identifier
+    # @param start_at [Time, nil] start time for report
+    # @param end_at [Time, nil] end time for report  
+    # @return [Array<AveragePrice>] average price data points
+    # @example
+    #   client = BudaApi::PublicClient.new
+    #   start_time = Time.now - 86400  # 24 hours ago
+    #   prices = client.average_prices_report("BTC-CLP", start_at: start_time)
+    def average_prices_report(market_id, start_at: nil, end_at: nil)
+      get_report(market_id, ReportType::AVERAGE_PRICES, start_at, end_at) do |report_data|
+        AveragePrice.new(report_data)
+      end
+    end
+
+    # Get candlestick report
+    #
+    # @param market_id [String] market identifier
+    # @param start_at [Time, nil] start time for report
+    # @param end_at [Time, nil] end time for report
+    # @return [Array<Candlestick>] candlestick data points
+    # @example
+    #   client = BudaApi::PublicClient.new
+    #   start_time = Time.now - 86400  # 24 hours ago
+    #   candles = client.candlestick_report("BTC-CLP", start_at: start_time)
+    def candlestick_report(market_id, start_at: nil, end_at: nil)
+      get_report(market_id, ReportType::CANDLESTICK, start_at, end_at) do |report_data|
+        Candlestick.new(report_data)
+      end
+    end
+
+    private
+
+    def get_report(market_id, report_type, start_at, end_at)
+      validate_required_params({ 
+        market_id: market_id,
+        report_type: report_type 
+      }, [:market_id, :report_type])
+      
+      validate_param_values({ 
+        market_id: market_id,
+        report_type: report_type 
+      }, { 
+        market_id: Market::ALL,
+        report_type: ReportType::ALL 
+      })
+
+      params = normalize_params({
+        report_type: report_type,
+        from: start_at&.to_i,
+        to: end_at&.to_i
+      })
+
+      BudaApi::Logger.info("Fetching #{report_type} report for #{market_id}")
+      
+      response = get("markets/#{market_id}/reports", params)
+      reports_data = response["reports"] || []
+      
+      reports_data.map { |report_data| yield(report_data) }
+    end
+  end
+end

data/lib/buda_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BudaApi
+  VERSION = "1.0.0"
+end

data/lib/buda_api.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "buda_api/version"
+require_relative "buda_api/client"
+require_relative "buda_api/public_client"
+require_relative "buda_api/authenticated_client"
+require_relative "buda_api/models"
+require_relative "buda_api/constants"
+require_relative "buda_api/errors"
+require_relative "buda_api/logger"
+
+# BudaApi is the main module for the Buda.com API Ruby SDK
+#
+# This SDK provides comprehensive access to the Buda.com cryptocurrency exchange API
+# with built-in error handling, debugging capabilities, and extensive examples.
+#
+# @example Basic usage with public API
+#   client = BudaApi::PublicClient.new
+#   markets = client.markets
+#   ticker = client.ticker("BTC-CLP")
+#
+# @example Authenticated API usage
+#   client = BudaApi::AuthenticatedClient.new(api_key: "your_key", api_secret: "your_secret")
+#   balance = client.balance("BTC")
+#   order = client.place_order("BTC-CLP", "ask", "limit", 1000000, 0.001)
+#
+module BudaApi
+  class Error < StandardError; end
+
+  # Configure the SDK with global settings
+  class Configuration
+    attr_accessor :base_url, :timeout, :retries, :debug_mode, :logger_level
+
+    def initialize
+      @base_url = "https://www.buda.com/api/v2/"
+      @timeout = 30
+      @retries = 3
+      @debug_mode = false
+      @logger_level = :info
+    end
+  end
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  # Configure the SDK
+  # 
+  # @yield [Configuration] configuration object
+  # @example
+  #   BudaApi.configure do |config|
+  #     config.debug_mode = true
+  #     config.timeout = 60
+  #   end
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+
+  # Get current configuration
+  # @return [Configuration] current configuration
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Convenience method to create a public client
+  # @param options [Hash] client options
+  # @return [PublicClient] new public client instance
+  def self.public_client(options = {})
+    PublicClient.new(options)
+  end
+
+  # Convenience method to create an authenticated client
+  # @param api_key [String] API key
+  # @param api_secret [String] API secret
+  # @param options [Hash] additional client options
+  # @return [AuthenticatedClient] new authenticated client instance
+  def self.authenticated_client(api_key:, api_secret:, **options)
+    AuthenticatedClient.new(api_key: api_key, api_secret: api_secret, **options)
+  end
+end