bank_of_thailand 0.1.0

data/lib/bank_of_thailand/client.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+module BankOfThailand
+  # HTTP client for making requests to the BOT API
+  class Client
+    # @return [Configuration] the configuration instance
+    attr_reader :config
+
+    # Initialize a new Client
+    # @param config [Configuration, nil] Optional configuration instance
+    # @yield [Configuration] optional configuration block
+    #
+    # @example With global configuration
+    #   client = BankOfThailand::Client.new
+    #
+    # @example With instance configuration
+    #   client = BankOfThailand::Client.new do |config|
+    #     config.api_token = "your_token"
+    #   end
+    def initialize(config = nil)
+      @config = config || BankOfThailand.configuration.dup
+      yield(@config) if block_given?
+      @config.validate!
+    end
+
+    # Access exchange rate endpoints
+    # @return [Resources::ExchangeRate]
+    def exchange_rate
+      @exchange_rate ||= Resources::ExchangeRate.new(self)
+    end
+
+    # Access debt securities auction endpoints
+    # @return [Resources::DebtSecurities]
+    def debt_securities
+      @debt_securities ||= Resources::DebtSecurities.new(self)
+    end
+
+    # Access license check endpoints
+    # @return [Resources::LicenseCheck]
+    def license_check
+      @license_check ||= Resources::LicenseCheck.new(self)
+    end
+
+    # Access average exchange rate endpoints
+    # @return [AverageExchangeRate]
+    def average_exchange_rate
+      @average_exchange_rate ||= AverageExchangeRate.new(self)
+    end
+
+    # Access deposit rate endpoints
+    # @return [DepositRate]
+    def deposit_rate
+      @deposit_rate ||= DepositRate.new(self)
+    end
+
+    # Access financial holidays endpoints
+    # @return [FinancialHolidays]
+    def financial_holidays
+      @financial_holidays ||= FinancialHolidays.new(self)
+    end
+
+    # Access interbank rate endpoints
+    # @return [InterbankRate]
+    def interbank_rate
+      @interbank_rate ||= InterbankRate.new(self)
+    end
+
+    # Access loan rate endpoints
+    # @return [LoanRate]
+    def loan_rate
+      @loan_rate ||= LoanRate.new(self)
+    end
+
+    # Access swap point endpoints
+    # @return [SwapPoint]
+    def swap_point
+      @swap_point ||= SwapPoint.new(self)
+    end
+
+    # Access implied rate endpoints
+    # @return [ImpliedRate]
+    def implied_rate
+      @implied_rate ||= ImpliedRate.new(self)
+    end
+
+    # Access search series endpoints
+    # @return [SearchSeries]
+    def search_series
+      @search_series ||= SearchSeries.new(self)
+    end
+
+    # Make a GET request
+    # @param path [String] API endpoint path
+    # @param params [Hash] Query parameters
+    # @return [Hash] Parsed JSON response
+    # @raise [RequestError] if request fails
+    def get(path, params = {})
+      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 JSON response
+    # @raise [RequestError] if request fails
+    def post(path, body: {}, params: {})
+      request(:post, path, body: body, params: params)
+    end
+
+    private
+
+    # Make an HTTP request
+    # @param method [Symbol] HTTP method (:get, :post, etc.)
+    # @param path [String] API endpoint path (can be full URL or relative path)
+    # @param params [Hash] Query parameters
+    # @param body [Hash] Request body
+    # @return [Hash] Parsed response
+    # @raise [RequestError] if request fails
+    def request(method, path, params: {}, body: nil)
+      # Determine if path is a full URL or relative path
+      url = if path.start_with?("http://", "https://")
+              path
+            else
+              "#{config.base_url}#{path}"
+            end
+
+      response = Faraday.send(method, url) do |req|
+        req.headers["Authorization"] = config.api_token
+        req.headers["Content-Type"] = "application/json"
+        req.params = params if params.any?
+        req.body = body.to_json if body
+        req.options.timeout = config.timeout
+        req.options.open_timeout = config.timeout
+      end
+
+      handle_response(response)
+    rescue Faraday::TimeoutError => e
+      raise RequestError, "Request timeout: #{e.message}"
+    rescue Faraday::ConnectionFailed => e
+      raise RequestError, "Connection failed: #{e.message}"
+    rescue Faraday::Error => e
+      raise RequestError, "Request failed: #{e.message}"
+    end
+
+    # Handle HTTP response
+    # @param response [Faraday::Response] HTTP response
+    # @return [Hash] Parsed response body
+    # @raise [RequestError] if response indicates an error
+    def handle_response(response)
+      case response.status
+      when 200..299
+        parse_json(response.body)
+      when 401
+        raise AuthenticationError.new("Authentication failed. Check your API token.", response)
+      when 403
+        raise AuthenticationError.new(
+          "Access forbidden. Your token may not have permission for this resource.",
+          response
+        )
+      when 404
+        raise NotFoundError.new("Resource not found: #{response.env.url}", response)
+      when 429
+        retry_after = response.headers["retry-after"]&.to_i
+        raise RateLimitError.new("Rate limit exceeded", response, retry_after)
+      when 500..599
+        raise ServerError.new("Server error (#{response.status})", response)
+      else
+        raise RequestError.new("Unexpected response status: #{response.status}", response)
+      end
+    end
+
+    # Parse JSON response
+    # @param body [String] Response body
+    # @return [Hash] Parsed JSON
+    def parse_json(body)
+      return {} if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise RequestError, "Invalid JSON response: #{e.message}"
+    end
+  end
+end

data/lib/bank_of_thailand/configuration.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module BankOfThailand
+  # Configuration for the BankOfThailand API client
+  class Configuration
+    # @return [String] API token for authentication
+    attr_accessor :api_token
+
+    # @return [String] Base URL for the BOT API gateway
+    attr_accessor :base_url
+
+    # @return [Integer] Request timeout in seconds
+    attr_accessor :timeout
+
+    # @return [Integer] Number of retry attempts for failed requests
+    attr_accessor :max_retries
+
+    # @return [Logger, nil] Logger instance for debugging
+    attr_accessor :logger
+
+    # Default base URL for the BOT API
+    DEFAULT_BASE_URL = "https://gateway.api.bot.or.th"
+
+    # Default timeout in seconds
+    DEFAULT_TIMEOUT = 30
+
+    # Default number of retries
+    DEFAULT_MAX_RETRIES = 3
+
+    # Initialize a new Configuration instance
+    def initialize
+      @api_token = nil
+      @base_url = DEFAULT_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+      @max_retries = DEFAULT_MAX_RETRIES
+      @logger = nil
+    end
+
+    # Validate the configuration
+    # @raise [ConfigurationError] if configuration is invalid
+    # @return [Boolean] true if valid
+    def validate!
+      raise ConfigurationError, "API token is required" if api_token.nil? || api_token.empty?
+      raise ConfigurationError, "Base URL cannot be empty" if base_url.nil? || base_url.empty?
+
+      true
+    end
+
+    # Check if configuration is valid
+    # @return [Boolean] true if valid, false otherwise
+    def valid?
+      validate!
+      true
+    rescue ConfigurationError
+      false
+    end
+  end
+
+  class << self
+    # @return [Configuration] the global configuration instance
+    attr_writer :configuration
+
+    # Get the global configuration
+    # @return [Configuration] the configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the gem
+    # @yield [Configuration] the configuration instance
+    # @return [void]
+    #
+    # @example
+    #   BankOfThailand.configure do |config|
+    #     config.api_token = "your_token_here"
+    #     config.timeout = 60
+    #   end
+    def configure
+      yield(configuration)
+    end
+
+    # Reset configuration to defaults
+    # @return [Configuration] new configuration instance
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/bank_of_thailand/errors.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module BankOfThailand
+  # Base error class for all BankOfThailand errors
+  class Error < StandardError; end
+
+  # Raised when API request fails
+  class RequestError < Error
+    attr_reader :response
+
+    # @param message [String] Error message
+    # @param response [Faraday::Response, nil] HTTP response object
+    def initialize(message, response = nil)
+      @response = response
+      super(message)
+    end
+  end
+
+  # Raised when authentication fails
+  class AuthenticationError < RequestError; end
+
+  # Raised when the API token is missing or invalid
+  class InvalidTokenError < AuthenticationError; end
+
+  # Raised when the requested resource is not found
+  class NotFoundError < RequestError; end
+
+  # Raised when rate limit is exceeded
+  class RateLimitError < RequestError
+    attr_reader :retry_after
+
+    # @param message [String] Error message
+    # @param response [Faraday::Response, nil] HTTP response object
+    # @param retry_after [Integer, nil] Seconds to wait before retrying
+    def initialize(message, response = nil, retry_after = nil)
+      @retry_after = retry_after
+      super(message, response)
+    end
+  end
+
+  # Raised when server returns 5xx error
+  class ServerError < RequestError; end
+
+  # Raised when configuration is invalid
+  class ConfigurationError < Error; end
+end

data/lib/bank_of_thailand/resource.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module BankOfThailand
+  # Base class for API resources
+  class Resource
+    # @return [Client] the API client instance
+    attr_reader :client
+
+    # Initialize a new Resource
+    # @param client [Client] API client instance
+    def initialize(client)
+      @client = client
+    end
+
+    private
+
+    # Make a GET request
+    # @param path [String] API endpoint path
+    # @param params [Hash] Query parameters
+    # @return [Hash] Response data
+    def get(path, params = {})
+      client.get(path, params)
+    end
+
+    # Make a POST request
+    # @param path [String] API endpoint path
+    # @param body [Hash] Request body
+    # @param params [Hash] Query parameters
+    # @return [Hash] Response data
+    def post(path, body: {}, params: {})
+      client.post(path, body: body, params: params)
+    end
+  end
+end

data/lib/bank_of_thailand/resources/average_exchange_rate.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module BankOfThailand
+  # Average Exchange Rate - THB / Foreign Currency resource
+  #
+  # This resource provides access to daily average exchange rates between Thai Baht
+  # and 19 foreign currencies from commercial banks in Thailand.
+  #
+  # @example Get daily average exchange rates
+  #   client = BankOfThailand.client
+  #   rates = client.average_exchange_rate.daily(
+  #     start_period: "2024-01-01",
+  #     end_period: "2024-01-31",
+  #     currency: "USD"
+  #   )
+  class AverageExchangeRate < Resource
+    BASE_URL = "https://gateway.api.bot.or.th/Stat-ExchangeRate/v2"
+
+    # Get daily average exchange rates
+    #
+    # @param start_period [String] Start period date (YYYY-MM-DD)
+    # @param end_period [String] End period date (YYYY-MM-DD)
+    # @param currency [String, nil] Foreign currency code (optional)
+    # @return [Hash] Response containing daily average exchange rate data
+    # @raise [BankOfThailand::Error] if the request fails
+    def daily(start_period:, end_period:, currency: nil)
+      params = { start_period: start_period, end_period: end_period }
+      params[:currency] = currency if currency
+
+      get_with_base_url("/DAILY_AVG_EXG_RATE/", params)
+    end
+
+    # Get monthly average exchange rates
+    #
+    # @param start_period [String] Start period (YYYY-MM)
+    # @param end_period [String] End period (YYYY-MM)
+    # @param currency [String, nil] Foreign currency code (optional)
+    # @return [Hash] Response containing monthly average exchange rate data
+    # @raise [BankOfThailand::Error] if the request fails
+    def monthly(start_period:, end_period:, currency: nil)
+      params = { start_period: start_period, end_period: end_period }
+      params[:currency] = currency if currency
+
+      get_with_base_url("/MONTHLY_AVG_EXG_RATE/", params)
+    end
+
+    # Get quarterly average exchange rates
+    #
+    # @param start_period [String] Start period (YYYY-QN, e.g., 2024-Q1)
+    # @param end_period [String] End period (YYYY-QN)
+    # @param currency [String, nil] Foreign currency code (optional)
+    # @return [Hash] Response containing quarterly average exchange rate data
+    # @raise [BankOfThailand::Error] if the request fails
+    def quarterly(start_period:, end_period:, currency: nil)
+      params = { start_period: start_period, end_period: end_period }
+      params[:currency] = currency if currency
+
+      get_with_base_url("/QUARTERLY_AVG_EXG_RATE/", params)
+    end
+
+    # Get annual average exchange rates
+    #
+    # @param start_period [String] Start period (YYYY)
+    # @param end_period [String] End period (YYYY)
+    # @param currency [String, nil] Foreign currency code (optional)
+    # @return [Hash] Response containing annual average exchange rate data
+    # @raise [BankOfThailand::Error] if the request fails
+    def annual(start_period:, end_period:, currency: nil)
+      params = { start_period: start_period, end_period: end_period }
+      params[:currency] = currency if currency
+
+      get_with_base_url("/ANNUAL_AVG_EXG_RATE/", params)
+    end
+
+    private
+
+    def get_with_base_url(path, params = {})
+      @client.get("#{BASE_URL}#{path}", params)
+    end
+  end
+end

data/lib/bank_of_thailand/resources/deposit_rate.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module BankOfThailand
+  # Deposit Interest Rates resource
+  #
+  # This resource provides access to deposit interest rates for individuals
+  # from commercial banks in Thailand.
+  #
+  # @example Get deposit rates
+  #   client = BankOfThailand.client
+  #   rates = client.deposit_rate.rates(
+  #     start_period: "2024-01-01",
+  #     end_period: "2024-01-31"
+  #   )
+  class DepositRate < Resource
+    BASE_URL = "https://gateway.api.bot.or.th/DepositRate/v2"
+
+    # Get deposit interest rates for individuals of commercial banks
+    #
+    # @param start_period [String] Start period date (YYYY-MM-DD)
+    # @param end_period [String] End period date (YYYY-MM-DD)
+    # @return [Hash] Response containing deposit interest rate data
+    # @raise [BankOfThailand::Error] if the request fails
+    def rates(start_period:, end_period:)
+      params = { start_period: start_period, end_period: end_period }
+      get_with_base_url("/deposit_rate/", params)
+    end
+
+    # Get min-max deposit interest rates for individuals of commercial banks
+    #
+    # @param start_period [String] Start period date (YYYY-MM-DD)
+    # @param end_period [String] End period date (YYYY-MM-DD)
+    # @return [Hash] Response containing min-max deposit interest rate data
+    # @raise [BankOfThailand::Error] if the request fails
+    def average_rates(start_period:, end_period:)
+      params = { start_period: start_period, end_period: end_period }
+      get_with_base_url("/avg_deposit_rate/", params)
+    end
+
+    private
+
+    def get_with_base_url(path, params = {})
+      @client.get("#{BASE_URL}#{path}", params)
+    end
+  end
+end

data/lib/bank_of_thailand/resources/exchange_rate.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module BankOfThailand
+  module Resources
+    # Weighted-average Interbank Exchange Rate - THB / USD
+    #
+    # This API provides weighted-average interbank exchange rates calculated from
+    # daily interbank purchases and sales of US Dollar (against THB) for transactions
+    # worth more than or equal to 1 million USD.
+    #
+    # @see https://gateway.api.bot.or.th/Stat-ReferenceRate/v2
+    class ExchangeRate < Resource
+      # Base URL for this API (overrides the global base URL)
+      BASE_URL = "https://gateway.api.bot.or.th/Stat-ReferenceRate/v2"
+
+      # Get daily weighted-average interbank exchange rate
+      #
+      # @param start_period [String] Start date in YYYY-MM-DD format (e.g., "2017-06-30")
+      # @param end_period [String] End date in YYYY-MM-DD format (e.g., "2017-06-30")
+      # @return [Hash] Response containing daily exchange rate data
+      #
+      # @example Get daily rates for a date range
+      #   client.exchange_rate.daily(
+      #     start_period: "2025-01-01",
+      #     end_period: "2025-01-31"
+      #   )
+      def daily(start_period:, end_period:)
+        get_with_base_url(
+          "#{BASE_URL}/DAILY_REF_RATE/",
+          start_period: start_period,
+          end_period: end_period
+        )
+      end
+
+      # Get monthly weighted-average interbank exchange rate
+      #
+      # @param start_period [String] Start period in YYYY-MM format (e.g., "2017-06")
+      # @param end_period [String] End period in YYYY-MM format (e.g., "2017-06")
+      # @return [Hash] Response containing monthly exchange rate data
+      #
+      # @example Get monthly rates
+      #   client.exchange_rate.monthly(
+      #     start_period: "2025-01",
+      #     end_period: "2025-03"
+      #   )
+      def monthly(start_period:, end_period:)
+        get_with_base_url(
+          "#{BASE_URL}/MONTHLY_REF_RATE/",
+          start_period: start_period,
+          end_period: end_period
+        )
+      end
+
+      # Get quarterly weighted-average interbank exchange rate
+      #
+      # @param start_period [String] Start period in YYYY-QN format (e.g., "2017-Q1")
+      # @param end_period [String] End period in YYYY-QN format (e.g., "2017-Q1")
+      # @return [Hash] Response containing quarterly exchange rate data
+      #
+      # @example Get quarterly rates
+      #   client.exchange_rate.quarterly(
+      #     start_period: "2025-Q1",
+      #     end_period: "2025-Q2"
+      #   )
+      def quarterly(start_period:, end_period:)
+        get_with_base_url(
+          "#{BASE_URL}/QUARTERLY_REF_RATE/",
+          start_period: start_period,
+          end_period: end_period
+        )
+      end
+
+      # Get annual weighted-average interbank exchange rate
+      #
+      # @param start_period [String] Start year in YYYY format (e.g., "2017")
+      # @param end_period [String] End year in YYYY format (e.g., "2017")
+      # @return [Hash] Response containing annual exchange rate data
+      #
+      # @example Get annual rates
+      #   client.exchange_rate.annual(
+      #     start_period: "2020",
+      #     end_period: "2024"
+      #   )
+      def annual(start_period:, end_period:)
+        get_with_base_url(
+          "#{BASE_URL}/ANNUAL_REF_RATE/",
+          start_period: start_period,
+          end_period: end_period
+        )
+      end
+
+      private
+
+      # Make a GET request with a custom base URL
+      # @param url [String] Full URL path
+      # @param params [Hash] Query parameters
+      # @return [Hash] Response data
+      def get_with_base_url(url, params = {})
+        client.get(url, params)
+      end
+    end
+  end
+end

data/lib/bank_of_thailand/resources/financial_holidays.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module BankOfThailand
+  # Financial Institutions' Holidays resource
+  #
+  # This resource provides access to the list of holidays for financial institutions in Thailand.
+  #
+  # @example Get holidays for a year
+  #   client = BankOfThailand.client
+  #   holidays = client.financial_holidays.list(year: "2024")
+  class FinancialHolidays < Resource
+    BASE_URL = "https://gateway.api.bot.or.th/financial-institutions-holidays"
+
+    # Get financial institutions' holidays for a specific year
+    #
+    # @param year [String] Year in format YYYY (e.g., "2024")
+    # @return [Array<Hash>] Array of holiday data
+    # @raise [BankOfThailand::Error] if the request fails
+    def list(year:)
+      params = { year: year }
+      get_with_base_url("/", params)
+    end
+
+    private
+
+    def get_with_base_url(path, params = {})
+      @client.get("#{BASE_URL}#{path}", params)
+    end
+  end
+end

data/lib/bank_of_thailand/resources/implied_rate.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module BankOfThailand
+  # Thai Baht Implied Interest Rates resource
+  #
+  # This resource provides access to Thai Baht implied interest rates derived from
+  # the swap market.
+  #
+  # @example Get implied interest rates
+  #   client = BankOfThailand.client
+  #   rates = client.implied_rate.rates(
+  #     start_period: "2024-01-01",
+  #     end_period: "2024-01-31",
+  #     rate_type: "ONSHORE : T/N"
+  #   )
+  class ImpliedRate < Resource
+    BASE_URL = "https://gateway.api.bot.or.th/Stat-ThaiBahtImpliedInterestRate/v2/THB_IMPL_INT_RATE"
+
+    # Get Thai Baht implied interest rates
+    #
+    # @param start_period [String] Start period date (YYYY-MM-DD)
+    # @param end_period [String] End period date (YYYY-MM-DD)
+    # @param rate_type [String, nil] Rate type (e.g., "ONSHORE : T/N") (optional)
+    # @return [Hash] Response containing Thai Baht implied interest rate data
+    # @raise [BankOfThailand::Error] if the request fails
+    def rates(start_period:, end_period:, rate_type: nil)
+      params = { start_period: start_period, end_period: end_period }
+      params[:rate_type] = rate_type if rate_type
+
+      get_with_base_url("/", params)
+    end
+
+    private
+
+    def get_with_base_url(path, params = {})
+      @client.get("#{BASE_URL}#{path}", params)
+    end
+  end
+end

data/lib/bank_of_thailand/resources/interbank_rate.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module BankOfThailand
+  # Interbank Transaction Rates resource
+  #
+  # This resource provides access to interbank transaction rates from commercial banks
+  # and financial institutions in Thailand.
+  #
+  # @example Get interbank rates
+  #   client = BankOfThailand.client
+  #   rates = client.interbank_rate.rates(
+  #     start_period: "2024-01-01",
+  #     end_period: "2024-01-31",
+  #     term_type: "O/N"
+  #   )
+  class InterbankRate < Resource
+    BASE_URL = "https://gateway.api.bot.or.th/Stat-InterbankTransactionRate/v2/INTRBNK_TXN_RATE"
+
+    # Get interbank transaction rates
+    #
+    # @param start_period [String] Start period date (YYYY-MM-DD)
+    # @param end_period [String] End period date (YYYY-MM-DD)
+    # @param term_type [String, nil] Term type (e.g., "O/N", "T/N") (optional)
+    # @return [Hash] Response containing interbank transaction rate data
+    # @raise [BankOfThailand::Error] if the request fails
+    def rates(start_period:, end_period:, term_type: nil)
+      params = { start_period: start_period, end_period: end_period }
+      params[:term_type] = term_type if term_type
+
+      get_with_base_url("/", params)
+    end
+
+    private
+
+    def get_with_base_url(path, params = {})
+      @client.get("#{BASE_URL}#{path}", params)
+    end
+  end
+end