bank_of_thailand 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c8ed6b63a147c446647a9a14d22496586de29fcb34841bb87eb1486a7307118
-  data.tar.gz: a5929c13399366bf2715621922c73c6565c8a98b2f6d5d172ce8520e3006c0d6
+  metadata.gz: e4e88cba8f1640985c4d18be3853c7072429a27df7f7d28c9bd490c13321826b
+  data.tar.gz: fe6da0cb6c0dd0a3f7f6a782f196bfd9ac969605b44f0f8b83a89af73afa641d
 SHA512:
-  metadata.gz: 2f18242c5e071d0e42f3123bf1a796427a693603bb8c6297c9ae98ef01585515ffe5cf9e6fbf332c3454e3a3ad28c678f3347ae09b58dd7d62407b137f932ac8
-  data.tar.gz: e237535be4e3f98f0953ac74b06e8bdde61f91e7ee8a70fd7665f5faeb46fa7ede942d552d3a2d4dc2e64ad85e7e99b9f4f09b99f6f9a2789ba971430caef405
+  metadata.gz: 5816fa3b3f30eb7c86bff63ec7e67c95b16730ec73dd570c4187a2cbbaaed5edeccd77150b08d5d18613df959f2c1f56c7a06b3920b7f47be27c2d138953e209
+  data.tar.gz: c8e516160e94ca7e361b4088894e76e6e2a686c63fa68c06fff1189ebf1e76c886dee72fbe8656361bace652c9fd8b7fa3e04c1fb66ee59de8570b57d9fd9918

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-11-04
+
+### Added
+- **Response wrapper class** with comprehensive data analysis utilities
+  - Basic statistics: `count`, `first`, `last`, `min`, `max`, `sum`, `average`/`mean`
+  - Date range analysis: `date_range`, `period_days`, `complete?`, `missing_dates`
+  - Rate change calculations: `change`, `daily_changes`, `volatility`, `trend`
+  - CSV export: `to_csv` method for easy data export
+  - Backward compatibility: `[]` and `dig` methods for hash-like access
+- Enhanced test coverage (117 examples, 100% pass rate)
+- Updated README with Response class documentation
+
+### Changed
+- All API methods now return `Response` objects instead of raw hashes
+- Improved error handling for different response formats (arrays, hashes, edge cases)
+
 ## [0.1.0] - 2025-11-03
 
 ### Added

data/README.md

@@ -9,9 +9,10 @@ A Ruby gem for accessing the Bank of Thailand's public API services. This gem pr
 
 - **Token-based Authentication** - Secure API access using BOT's authorization system
 - **11 API Resources** - Complete coverage of all documented BOT API products
+- **Smart Response Objects** - Built-in statistics, CSV export, and data analysis
 - **Type Safety** - Comprehensive error handling with custom exception classes
 - **Flexible Configuration** - Global or instance-level configuration options
-- **Full Test Coverage** - 66 examples with 100% pass rate
+- **Full Test Coverage** - 117 examples with 100% pass rate
 - **YARD Documentation** - Complete API documentation for all endpoints
 
 ## Installation
@@ -77,15 +78,7 @@ client = BankOfThailand::Client.new do |config|
 end
 ```
 
-### Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `api_token` | String | `nil` | **Required.** Your BOT API token from the portal |
-| `base_url` | String | `https://gateway.api.bot.or.th` | Base gateway URL (rarely needs changing) |
-| `timeout` | Integer | `30` | Request timeout in seconds |
-| `max_retries` | Integer | `3` | Number of retry attempts for failed requests |
-| `logger` | Logger | `nil` | Optional logger for debugging |
+**Available Options:** `api_token` (required), `base_url`, `timeout`, `max_retries`, `logger`
 
 ## Usage
 
@@ -116,6 +109,42 @@ client.financial_holidays     # Financial Institutions' Holidays
 client.search_series          # Search Stat APIs
 ```
 
+### Working with Responses
+
+All API calls return a `Response` object with built-in data analysis features:
+
+```ruby
+rates = client.exchange_rate.daily(
+  start_period: "2025-01-01",
+  end_period: "2025-01-31"
+)
+
+# Access data
+rates.data                     # Array of data points
+rates.count                    # Number of records
+rates.first                    # First record
+rates.last                     # Last record
+
+# Quick statistics
+rates.average("value")         # Average rate
+rates.min("value")             # Minimum rate
+rates.max("value")             # Maximum rate
+
+# Analyze changes
+rates.change("value")          # Overall change with percentage
+rates.volatility("value")      # Daily volatility
+rates.trend("value")           # :up, :down, or :flat
+
+# Export to CSV
+rates.to_csv("rates.csv")      # Save to file
+csv_string = rates.to_csv      # Get CSV string
+
+# Check completeness
+rates.date_range               # ["2025-01-01", "2025-01-31"]
+rates.complete?                # All dates present?
+rates.missing_dates            # Array of missing dates
+```
+
 ### Exchange Rates
 
 #### Weighted-average Interbank Exchange Rate (THB/USD)
@@ -177,12 +206,6 @@ implied = client.implied_rate.rates(
 
 ### Securities & Markets
 
-```ruby
-# Debt securities auction results
-```
-
-### Securities & Markets
-
 ```ruby
 # Debt securities auction results
 results = client.debt_securities.auction_results(
@@ -223,32 +246,22 @@ series = client.search_series.search(keyword: "government debt")
 
 ## Error Handling
 
+The gem provides specific exception classes for different error scenarios:
+
 ```ruby
 begin
-  client.exchange_rate.daily
+  rates = client.exchange_rate.daily(start_period: "2025-01-01", end_period: "2025-01-31")
+rescue BankOfThailand::AuthenticationError
+  puts "Invalid API token"
 rescue BankOfThailand::RateLimitError => e
-  retry_after = e.retry_after
-rescue BankOfThailand::APIError => e
-  puts "API error: #{e.message}"
+  sleep e.retry_after
+  retry
+rescue BankOfThailand::RequestError => e
+  puts "Request failed: #{e.message}"
 end
 ```
 
-### Exception Hierarchy
-
-```
-BankOfThailand::Error (StandardError)
-├── ConfigurationError
-└── RequestError
-    ├── AuthenticationError
-    │   └── InvalidTokenError
-    ├── NotFoundError
-    ├── RateLimitError
-    └── ServerError
-```
-
-## Rate Limits
-
-Rate limits vary by API product. The gem automatically handles rate limiting errors and provides retry information via `RateLimitError#retry_after`.
+**Exception Types:** `ConfigurationError`, `AuthenticationError`, `NotFoundError`, `RateLimitError`, `ServerError`
 
 ## Development
 

data/lib/bank_of_thailand/client.rb

@@ -149,12 +149,13 @@ module BankOfThailand
 
     # Handle HTTP response
     # @param response [Faraday::Response] HTTP response
-    # @return [Hash] Parsed response body
+    # @return [Response] Wrapped response object
     # @raise [RequestError] if response indicates an error
     def handle_response(response)
       case response.status
       when 200..299
-        parse_json(response.body)
+        json = parse_json(response.body)
+        Response.new(json)
       when 401
         raise AuthenticationError.new("Authentication failed. Check your API token.", response)
       when 403
@@ -176,11 +177,13 @@ module BankOfThailand
 
     # Parse JSON response
     # @param body [String] Response body
-    # @return [Hash] Parsed JSON
+    # @return [Hash, Array] Parsed JSON
     def parse_json(body)
       return {} if body.nil? || body.empty?
 
-      JSON.parse(body)
+      result = JSON.parse(body)
+      # Ensure we return a Hash or Array, not a primitive
+      result.is_a?(Hash) || result.is_a?(Array) ? result : {}
     rescue JSON::ParserError => e
       raise RequestError, "Invalid JSON response: #{e.message}"
     end

data/lib/bank_of_thailand/response.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require "csv"
+require "date"
+
+module BankOfThailand
+  # Wrapper for API responses with convenience methods
+  class Response
+    # @return [Hash] the raw API response
+    attr_reader :raw
+
+    # @return [Array<Hash>] the extracted data array
+    attr_reader :data
+
+    # Initialize a new Response
+    # @param raw_response [Hash] the raw API response
+    def initialize(raw_response)
+      @raw = raw_response
+      @data = extract_data(raw_response)
+    end
+
+    # Allow hash-like access for backward compatibility
+    # @param key [String, Symbol] the key to access
+    # @return [Object] the value at the key
+    def [](key)
+      return nil unless raw.is_a?(Hash)
+
+      raw[key.to_s]
+    end
+
+    # Allow hash-like dig for backward compatibility
+    # @param keys [Array] the keys to dig through
+    # @return [Object] the value at the nested keys
+    def dig(*keys)
+      return nil unless raw.is_a?(Hash)
+
+      raw.dig(*keys.map(&:to_s))
+    end
+
+    # Count of data points
+    # @return [Integer] number of data points
+    def count
+      data.size
+    end
+
+    # First data point
+    # @return [Hash, nil] first data point or nil if empty
+    def first
+      data.first
+    end
+
+    # Last data point
+    # @return [Hash, nil] last data point or nil if empty
+    def last
+      data.last
+    end
+
+    # Extract numeric values for a column
+    # @param column [String] the column name
+    # @return [Array<Float>] array of numeric values
+    def values_for(column)
+      data.select { |row| row.is_a?(Hash) }.map { |row| row[column]&.to_f }.compact
+    end
+
+    # Minimum value for a column
+    # @param column [String] the column name
+    # @return [Float, nil] minimum value or nil if no data
+    def min(column)
+      values_for(column).min
+    end
+
+    # Maximum value for a column
+    # @param column [String] the column name
+    # @return [Float, nil] maximum value or nil if no data
+    def max(column)
+      values_for(column).max
+    end
+
+    # Sum of values for a column
+    # @param column [String] the column name
+    # @return [Float] sum of values
+    def sum(column)
+      values_for(column).sum
+    end
+
+    # Average value for a column
+    # @param column [String] the column name
+    # @return [Float] average value or 0 if no data
+    def average(column)
+      vals = values_for(column)
+      return 0.0 if vals.empty?
+
+      vals.sum / vals.size.to_f
+    end
+
+    alias mean average
+
+    # Date range covered by the data
+    # @return [Array<String>, nil] [start_date, end_date] or nil if no dates
+    def date_range
+      dates = data.select { |row| row.is_a?(Hash) }.map { |row| row["period"] || row["date"] }.compact
+      return nil if dates.empty?
+
+      dates.minmax
+    end
+
+    # Number of days in the period
+    # @return [Integer] number of days
+    def period_days
+      range = date_range
+      return 0 unless range
+
+      (Date.parse(range[1]) - Date.parse(range[0])).to_i + 1
+    rescue Date::Error
+      0
+    end
+
+    # Check if data is complete for the date range
+    # @return [Boolean] true if all expected days are present
+    def complete?
+      expected_days = period_days
+      return true if expected_days.zero?
+
+      count >= expected_days
+    end
+
+    # Find missing dates in the range
+    # @return [Array<Date>] array of missing dates
+    def missing_dates
+      return [] unless date_range
+
+      start_date = Date.parse(date_range[0])
+      end_date = Date.parse(date_range[1])
+      actual_dates = data.select { |row| row.is_a?(Hash) }.map { |row| Date.parse(row["period"] || row["date"]) }
+
+      (start_date..end_date).reject { |date| actual_dates.include?(date) }
+    rescue Date::Error
+      []
+    end
+
+    # Calculate change metrics for a column
+    # @param column [String] the column name (default: "value")
+    # @return [Hash, nil] hash with :absolute, :percentage, :first_value, :last_value
+    def change(column = "value")
+      vals = values_for(column)
+      return nil if vals.size < 2
+
+      first_val = vals.first
+      last_val = vals.last
+
+      {
+        absolute: last_val - first_val,
+        percentage: first_val.zero? ? 0.0 : ((last_val - first_val) / first_val * 100).round(4),
+        first_value: first_val,
+        last_value: last_val
+      }
+    end
+
+    # Calculate daily changes for a column
+    # @param column [String] the column name (default: "value")
+    # @return [Array<Hash>] array of change hashes with :absolute and :percentage
+    def daily_changes(column = "value")
+      vals = values_for(column)
+      return [] if vals.size < 2
+
+      vals.each_cons(2).map do |prev, curr|
+        {
+          absolute: curr - prev,
+          percentage: prev.zero? ? 0.0 : ((curr - prev) / prev * 100).round(4)
+        }
+      end
+    end
+
+    # Calculate volatility (standard deviation of daily percentage changes)
+    # @param column [String] the column name (default: "value")
+    # @return [Float] volatility as standard deviation
+    def volatility(column = "value")
+      changes = daily_changes(column).map { |c| c[:percentage] }
+      return 0.0 if changes.empty?
+
+      mean = changes.sum / changes.size.to_f
+      variance = changes.sum { |x| (x - mean)**2 } / changes.size.to_f
+      Math.sqrt(variance).round(4)
+    end
+
+    # Determine trend direction
+    # @param column [String] the column name (default: "value")
+    # @return [Symbol] :up, :down, or :flat
+    def trend(column = "value")
+      change_data = change(column)
+      return :flat unless change_data
+
+      pct = change_data[:percentage]
+
+      if pct > 1
+        :up
+      elsif pct < -1
+        :down
+      else
+        :flat
+      end
+    end
+
+    # Export data to CSV
+    # @param filename [String, nil] optional filename to save CSV
+    # @return [String] CSV string or filename if saved
+    def to_csv(filename = nil)
+      csv_data = CSV.generate do |csv|
+        csv << extract_headers
+        extract_rows.each { |row| csv << row }
+      end
+
+      if filename
+        File.write(filename, csv_data)
+        filename
+      else
+        csv_data
+      end
+    end
+
+    private
+
+    # Extract data array from API response
+    # @param response [Hash, Array, Object] raw API response
+    # @return [Array<Hash>] extracted data array
+    def extract_data(response)
+      # Handle array responses (e.g., financial holidays)
+      return response if response.is_a?(Array)
+
+      # Handle non-hash/non-array responses
+      return [] unless response.is_a?(Hash)
+
+      # Handle standard BOT API format with result.data
+      # Only dig if result exists and is a Hash
+      result_data = response["result"]
+      return [] unless result_data.is_a?(Hash)
+
+      result_data["data"] || []
+    end
+
+    # Extract CSV headers from data
+    # @return [Array<String>] array of header names
+    def extract_headers
+      return [] if data.empty?
+
+      first_row = data.first
+      case first_row
+      when Hash
+        first_row.keys
+      when Array
+        (1..first_row.size).map { |i| "column_#{i}" }
+      else
+        ["value"]
+      end
+    end
+
+    # Extract CSV rows from data
+    # @return [Array<Array>] array of row arrays
+    def extract_rows
+      data.map do |row|
+        case row
+        when Hash
+          row.values
+        when Array
+          row
+        else
+          [row]
+        end
+      end
+    end
+  end
+end

data/lib/bank_of_thailand/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BankOfThailand
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/bank_of_thailand.rb

@@ -3,6 +3,7 @@
 require_relative "bank_of_thailand/version"
 require_relative "bank_of_thailand/errors"
 require_relative "bank_of_thailand/configuration"
+require_relative "bank_of_thailand/response"
 require_relative "bank_of_thailand/client"
 require_relative "bank_of_thailand/resource"
 require_relative "bank_of_thailand/resources/exchange_rate"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bank_of_thailand
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Chayut Orapinpatipat
@@ -178,6 +178,7 @@ files:
 - lib/bank_of_thailand/resources/search_series.rb
 - lib/bank_of_thailand/resources/statistics.rb
 - lib/bank_of_thailand/resources/swap_point.rb
+- lib/bank_of_thailand/response.rb
 - lib/bank_of_thailand/version.rb
 - sig/bank_of_thailand.rbs
 homepage: https://github.com/chayuto/bank_of_thailand