twelvedata_ruby 0.3.0 → 0.4.0

data/lib/twelvedata_ruby/response.rb

@@ -1,156 +1,314 @@
 # frozen_string_literal: true
 
 require "csv"
+require "json"
+require "tempfile"
+
+# Handles API responses from Twelve Data
 module TwelvedataRuby
   class Response
-    CSV_COL_SEP = ";"
-    BODY_MAX_BYTESIZE = 16_000
-    HTTP_STATUSES = {http_error: (400..600), success: (200..299)}.freeze
-    CONTENT_TYPE_HANDLERS = {
-      json: {parser: :json_parser, dumper: :json_dumper},
-      csv: {parser: :csv_parser, dumper: :csv_dumper},
-      plain: {parser: :plain_parser, dumper: :to_s}
-    }.freeze
-
-    class << self
-      def resolve(http_response, request)
-        if http_status_codes.member?(http_response.status)
-          new(http_response: http_response, request: request)
-        else
-          resolve_error(http_response, request)
-        end
-      end
+  # CSV column separator used by Twelve Data
+  CSV_COL_SEP = ";"
 
-      def resolve_error(http_response, request)
-        error_attribs = if http_response.respond_to?(:error) && http_response.error
-                          {message: http_response.error.message, code: http_response.error.class.name}
-                        else
-                          {message: http_response.body.to_s, code: http_response.status}
-                        end
-        TwelvedataRuby::ResponseError.new(json: (error_attribs || {}), request: request)
-      end
+  # Maximum response body size to keep in memory
+  BODY_MAX_BYTESIZE = 16_000
+
+  # HTTP status code ranges
+  HTTP_STATUSES = {
+    http_error: (400..600),
+    success: (200..299),
+  }.freeze
+
+  # Content type handlers for different response formats
+  CONTENT_TYPE_HANDLERS = {
+    json: { parser: :parse_json, dumper: :dump_json },
+    csv: { parser: :parse_csv, dumper: :dump_csv },
+    plain: { parser: :parse_plain, dumper: :to_s },
+  }.freeze
 
-      def http_status_codes
-        @http_status_codes ||= HTTP_STATUSES.values.map(&:to_a).flatten
+  class << self
+    # Resolve HTTP response into Response or ResponseError
+    #
+    # @param http_response [HTTPX::Response] HTTP response from client
+    # @param request [Request] Original request object
+    # @return [Response, ResponseError] Resolved response or error
+    def resolve(http_response, request)
+      if success_status?(http_response.status)
+        new(http_response: http_response, request: request)
+      else
+        create_error_from_response(http_response, request)
       end
+    rescue StandardError => e
+      ResponseError.new(
+        message: "Failed to resolve response: #{e.message}",
+        request: request,
+        original_error: e,
+      )
     end
 
-    attr_reader :http_response, :headers, :body, :body_bytesize, :request
-
-    def initialize(http_response:, request:, headers: nil, body: nil)
-      self.http_response = http_response
+    # Get all valid HTTP status codes
+    #
+    # @return [Array<Integer>] Array of valid status codes
+    def valid_status_codes
+      @valid_status_codes ||= HTTP_STATUSES.values.flat_map(&:to_a)
     end
 
-    def attachment_filename
-      return nil unless headers["content-disposition"]
+    private
 
-      @attachment_filename ||= headers["content-disposition"].split("filename=").last.delete("\"")
+    def success_status?(status)
+      HTTP_STATUSES[:success].include?(status)
     end
 
-    def body_parser
-      CONTENT_TYPE_HANDLERS[content_type][:parser]
+    def create_error_from_response(http_response, request)
+      json_data = extract_error_data(http_response)
+      error_class = determine_error_class(http_response.status)
+      error_class.new(json_data:, request:, status_code: http_response.status, message: json_data[:message])
     end
 
-    def content_type
-      @content_type ||= headers["content-type"].match(%r{^.+/([a-z]+).*$})&.send(:[], 1)&.to_sym
+    def extract_error_data(http_response)
+      if http_response.respond_to?(:error) && http_response.error
+        {
+          message: http_response.error.message,
+          code: http_response.error.class.name,
+        }
+      else
+        {
+          message: http_response.body.to_s,
+          code: http_response.status,
+        }
+      end
     end
 
-    def csv_parser(io)
-      CSV.parse(io, headers: true, col_sep: CSV_COL_SEP)
-    end
+    def determine_error_class(status_code)
+      error_class_name = ResponseError.error_class_for_code(status_code, :http) ||
+                        ResponseError.error_class_for_code(status_code, :api)
 
-    def csv_dumper
-      parsed_body.is_a?(CSV::Table) ? parsed_body.to_csv(col_sep: CSV_COL_SEP) : nil
+      if error_class_name
+        TwelvedataRuby.const_get(error_class_name)
+      else
+        ResponseError
+      end
     end
+  end
 
-    def dumped_parsed_body
-      @dumped_parsed_body ||=
-        parsed_body.respond_to?(parsed_body_dumper) ? parsed_body.send(parsed_body_dumper) : send(parsed_body_dumper)
-    end
+  attr_reader :http_response, :headers, :body_bytesize, :request
 
-    def error
-      klass_name = ResponseError.error_code_klass(status_code, success_http_status? ? :api : :http)
-      return unless klass_name
-      TwelvedataRuby.const_get(klass_name)
-        .new(json: parsed_body, request: request, code: status_code, message: parsed_body)
-    end
+  # Initialize response with HTTP response and request
+  #
+  # @param http_response [HTTPX::Response] HTTP response object
+  # @param request [Request] Original request object
+  def initialize(http_response:, request:)
+    @http_response = http_response
+    @request = request
+    @headers = http_response.headers
+    @body_bytesize = http_response.body.bytesize
+    @parsed_body = nil
+  end
 
-    def http_status_code
-      http_response&.status
-    end
+  # Get attachment filename from response headers
+  #
+  # @return [String, nil] Filename if present in headers
+  def attachment_filename
+    return nil unless headers["content-disposition"]
 
-    def json_dumper
-      parsed_body.is_a?(Hash) ? JSON.dump(parsed_body) : nil
-    end
+    @attachment_filename ||= extract_filename_from_headers
+  end
 
-    def json_parser(io)
-      JSON.parse(io, symbolize_names: true)
-    end
+  # Get content type from response
+  #
+  # @return [Symbol, nil] Content type symbol (:json, :csv, :plain)
+  def content_type
+    @content_type ||= detect_content_type
+  end
 
-    def parsed_body
-      return @parsed_body if @parsed_body || http_response&.body.nil? || http_response&.body.closed?
-
-      begin
-        tmp_file = nil
-        if body_bytesize < BODY_MAX_BYTESIZE
-          @parsed_body = send(body_parser, http_response.body.to_s)
-        else
-          tmp_file = Tempfile.new
-          http_response.body.copy_to(tmp_file)
-          @parsed_body = send(body_parser, IO.read(tmp_file.path))
-        end
-      ensure
-        http_response.body.close
-        tmp_file&.close
-        tmp_file&.unlink
-      end
+  # Get parsed response body
+  #
+  # @return [Hash, CSV::Table, String] Parsed response data
+  def parsed_body
+    @parsed_body ||= parse_response_body
+  end
+  alias body parsed_body
 
-      @parsed_body
-    end
-    alias body parsed_body
-    alias parse_http_response_body parsed_body
+  # Get response error if present
+  #
+  # @return [ResponseError, nil] Error object if response contains an error
+  def error
+    return nil unless parsed_body.is_a?(Hash) && parsed_body.key?(:code)
 
-    def parsed_body_dumper
-      CONTENT_TYPE_HANDLERS[content_type][:dumper]
-    end
+    @error ||= create_response_error
+  end
 
-    def plain_parser(io=nil)
-      io.to_s || http_response.body.to_s
-    end
+  # Get HTTP status code
+  #
+  # @return [Integer] HTTP status code
+  def http_status_code
+    http_response.status
+  end
+
+  # Get API status code (from response body)
+  #
+  # @return [Integer] API status code
+  def status_code
+    @status_code ||= extract_status_code
+  end
+
+  # Check if HTTP response was successful
+  #
+  # @return [Boolean] True if HTTP status indicates success
+  def success?
+    HTTP_STATUSES[:success].include?(http_status_code)
+  end
+
+  # Save response to disk file
+  #
+  # @param file_path [String] Path to save file (defaults to attachment filename)
+  # @return [File, nil] File object if successful, nil otherwise
+  def save_to_file(file_path = nil)
+    file_path ||= attachment_filename
+    return nil unless file_path
 
-    def status_code
-      @status_code ||= parsed_body.is_a?(Hash) ? parsed_body[:code] : http_status_code
+    File.open(file_path, "w") do |file|
+      file.write(dump_parsed_body)
     end
+  rescue StandardError => e
+    raise ResponseError.new(
+      message: "Failed to save response to file: #{e.message}",
+      original_error: e,
+    )
+  end
+
+  # Get dumped (serialized) version of parsed body
+  #
+  # @return [String] Serialized response body
+  def dump_parsed_body
+    handler = CONTENT_TYPE_HANDLERS[content_type]
+    return parsed_body.to_s unless handler
 
-    def success_http_status?
-      @success_http_status ||= HTTP_STATUSES[:success].member?(http_status_code) || false
+    send(handler[:dumper])
+  end
+
+  # String representation of response
+  #
+  # @return [String] Response summary
+  def to_s
+    status_info = "#{http_status_code} (#{success? ? "success" : "error"})"
+    "Response: #{status_info}, Content-Type: #{content_type}, Size: #{body_bytesize} bytes"
+  end
+
+  # Detailed inspection of response
+  #
+  # @return [String] Detailed response information
+  def inspect
+    "#<#{self.class.name}:#{object_id} status=#{http_status_code} content_type=#{content_type} " \
+    "size=#{body_bytesize} error=#{error ? "yes" : "no"}>"
+  end
+
+  private
+
+  def extract_filename_from_headers
+    disposition = headers["content-disposition"]
+    return nil unless disposition
+
+    # Extract filename from Content-Disposition header
+    match = disposition.match(/filename="([^"]+)"/)
+    match ? match[1] : nil
+  end
+
+  def detect_content_type
+    content_type_header = headers["content-type"]
+    return :plain unless content_type_header
+
+    case content_type_header
+    when /json/
+      :json
+    when /csv/
+      :csv
+    else
+      :plain
     end
+  end
 
-    def to_disk_file(file_fullpath=attachment_filename)
-      return nil unless file_fullpath
+  def parse_response_body
+    return nil unless http_response.body
 
-      begin
-        file = File.open(file_fullpath, "w")
-        file.puts dumped_parsed_body
-        file
-      ensure
-        file&.close
+    begin
+      if body_bytesize < BODY_MAX_BYTESIZE
+        parse_body_content(http_response.body.to_s)
+      else
+        parse_large_body_content
       end
+    ensure
+      http_response.body.close if http_response.body.respond_to?(:close)
     end
+  end
 
-    private
+  def parse_body_content(content)
+    handler = CONTENT_TYPE_HANDLERS[content_type]
+    return content unless handler
 
-    attr_writer :request
+    send(handler[:parser], content)
+  end
 
-    def http_response=(http_resp)
-      @http_response = http_resp
-      @body_bytesize = http_resp.body.bytesize
-      self.headers = http_response.headers
-      parse_http_response_body
+  def parse_large_body_content
+    Tempfile.create do |temp_file|
+      http_response.body.copy_to(temp_file)
+      temp_file.rewind
+      parse_body_content(temp_file.read)
     end
+  end
 
-    def headers=(http_resp_headers)
-      @headers = http_response&.headers
+  def parse_json(content)
+    JSON.parse(content, symbolize_names: true)
+  rescue JSON::ParserError => e
+    raise ResponseError.new(
+      message: "Failed to parse JSON response: #{e.message}",
+      original_error: e,
+    )
+  end
+
+  def parse_csv(content)
+    CSV.parse(content, headers: true, col_sep: CSV_COL_SEP)
+  rescue CSV::MalformedCSVError => e
+    raise ResponseError.new(
+      message: "Failed to parse CSV response: #{e.message}",
+      original_error: e,
+    )
+  end
+
+  def parse_plain(content)
+    content.to_s
+  end
+
+  def dump_json
+    return nil unless parsed_body.is_a?(Hash)
+
+    JSON.dump(parsed_body)
+  end
+
+  def dump_csv
+    return nil unless parsed_body.is_a?(CSV::Table)
+
+    parsed_body.to_csv(col_sep: CSV_COL_SEP)
+  end
+
+  def extract_status_code
+    if parsed_body.is_a?(Hash) && parsed_body[:code]
+      parsed_body[:code]
+    else
+      http_status_code
     end
   end
+
+  def create_response_error
+    error_class_name = ResponseError.error_class_for_code(status_code)
+    error_class = error_class_name ? TwelvedataRuby.const_get(error_class_name) : ResponseError
+
+    error_class.new(
+      json_data: parsed_body,
+      request: request,
+      status_code: status_code,
+      message: parsed_body[:message],
+    )
+  end
+  end
 end

data/lib/twelvedata_ruby/utils.rb

@@ -1,36 +1,113 @@
 # frozen_string_literal: true
 
+# Utility methods for common operations
 module TwelvedataRuby
   module Utils
-    def self.demodulize(obj)
+  class << self
+    # Removes module namespace from class name
+    #
+    # @param obj [Object] Object to extract class name from
+    # @return [String] Class name without module namespace
+    #
+    # @example
+    #   Utils.demodulize(TwelvedataRuby::Error) #=> "Error"
+    def demodulize(obj)
       obj.to_s.gsub(/^.+::/, "")
     end
 
-    # Converts a string to integer an all integer or nothing
-    def self.to_d(obj, default_value=nil)
-      return obj if obj.is_a?(Integer)
-
-      obj.to_s.match(/^\d+$/) {|m| Integer(m[0]) } || default_value
+    # Converts string to integer with default fallback
+    #
+    # @param obj [Object] Object to convert
+    # @param default_value [Integer, nil] Default value if conversion fails
+    # @return [Integer, nil] Converted integer or default value
+    #
+    # @example
+    #   Utils.to_integer("123") #=> 123
+    #   Utils.to_integer("abc", 0) #=> 0
+    def to_integer(obj, default_value = nil)
+      obj.is_a?(Integer) ? obj : Integer(obj.to_s)
+    rescue ArgumentError
+      default_value
     end
 
-    def self.camelize(str)
+    # Converts snake_case to CamelCase
+    #
+    # @param str [String] String to convert
+    # @return [String] CamelCase string
+    #
+    # @example
+    #   Utils.camelize("snake_case") #=> "SnakeCase"
+    def camelize(str)
       str.to_s.split("_").map(&:capitalize).join
     end
 
-    def self.empty_to_nil(obj)
-      !obj.nil? && obj.empty? ? nil : obj
+    # Converts empty values to nil
+    #
+    # @param obj [Object] Object to check
+    # @return [Object, nil] Original object or nil if empty
+    #
+    # @example
+    #   Utils.empty_to_nil("") #=> nil
+    #   Utils.empty_to_nil("test") #=> "test"
+    def empty_to_nil(obj)
+      return nil if obj.nil?
+      return nil if obj.respond_to?(:empty?) && obj.empty?
+
+      obj
     end
 
-    def self.to_a(objects)
+    # Ensures return value is an array
+    #
+    # @param objects [Object] Single object or array
+    # @return [Array] Array containing the objects
+    #
+    # @example
+    #   Utils.to_array("test") #=> ["test"]
+    #   Utils.to_array(["a", "b"]) #=> ["a", "b"]
+    def to_array(objects)
       objects.is_a?(Array) ? objects : [objects]
     end
 
-    def self.call_block_if_truthy(truthy_val, return_this=nil, &block)
-      truthy_val ? block.call : return_this
+    # Executes block if condition is truthy
+    #
+    # @param condition [Object] Condition to evaluate
+    # @param default_return [Object] Default return value
+    # @yield Block to execute if condition is truthy
+    # @return [Object] Block result or default value
+    def execute_if_truthy(condition, default_return = nil)
+      return default_return unless condition && block_given?
+
+      yield
+    end
+
+    # Executes block only if condition is exactly true
+    #
+    # @param condition [Object] Condition to evaluate
+    # @yield Block to execute if condition is true
+    # @return [Object, nil] Block result or nil
+    def execute_if_true(condition, &block)
+      execute_if_truthy(condition == true, &block)
     end
 
-    def self.return_nil_unless_true(is_true, &block)
-      call_block_if_truthy(is_true == true) { block.call }
+    # Validates that a value is not blank
+    #
+    # @param value [Object] Value to validate
+    # @return [Boolean] True if value is present
+    def present?(value)
+      !blank?(value)
     end
+
+    # Checks if a value is blank (nil, empty, or whitespace-only)
+    #
+    # @param value [Object] Value to check
+    # @return [Boolean] True if value is blank
+    def blank?(value)
+      return true if value.nil?
+      return true if value.respond_to?(:empty?) && value.empty?
+      return true if value.is_a?(String) && value.strip.empty?
+
+      false
+    end
+  end
   end
 end

data/lib/twelvedata_ruby/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module TwelvedataRuby
+  # Current version of the TwelvedataRuby gem
+  VERSION = "0.4.0"
+end

data/lib/twelvedata_ruby.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "twelvedata_ruby/version"
 require_relative "twelvedata_ruby/utils"
 require_relative "twelvedata_ruby/error"
 require_relative "twelvedata_ruby/endpoint"
@@ -7,37 +8,47 @@ require_relative "twelvedata_ruby/request"
 require_relative "twelvedata_ruby/response"
 require_relative "twelvedata_ruby/client"
 
-# The one module that all the classes and modules of this gem are namespaced
-
+# TwelvedataRuby provides a Ruby interface for accessing Twelve Data's financial API
+#
+# @example Basic usage
+#   client = TwelvedataRuby.client(apikey: "your-api-key")
+#   response = client.quote(symbol: "AAPL")
+#   puts response.parsed_body
+#
+# @example Using environment variable for API key
+#   ENV['TWELVEDATA_API_KEY'] = 'your-api-key'
+#   client = TwelvedataRuby.client
+#   response = client.price(symbol: "GOOGL")
 module TwelvedataRuby
-  # Holds the current version
-  # @return [String] version number
-  VERSION = "0.3.0"
+  class << self
+    # Creates and configures a client instance
+    #
+    # @param options [Hash] Configuration options
+    # @option options [String] :apikey The Twelve Data API key
+    # @option options [Integer] :connect_timeout Connection timeout in milliseconds
+    # @option options [String] :apikey_env_var_name Environment variable name for API key
+    #
+    # @return [Client] Configured client instance
+    #
+    # @example Basic client creation
+    #   client = TwelvedataRuby.client(apikey: "your-key")
+    #
+    # @example With custom timeout
+    #   client = TwelvedataRuby.client(
+    #     apikey: "your-key",
+    #     connect_timeout: 5000
+    #   )
+    def client(**options)
+      client_instance = Client.instance
+      client_instance.configure(**options) if options.any?
+      client_instance
+    end
 
-  # A convenient and clearer way of getting and overriding default attribute values of the singleton `Client.instance`
-  #
-  # @param [Hash] options the optional Hash object that may contain values to override the cd Docdefaults
-  # @option options [Symbol, String] :apikey the private key from Twelvedata API key
-  # @option options [Integer, String] :connect_timeout milliseconds
-  #
-  #  @example Passing a nil options
-  #    TwelvedataRuby.client
-  #
-  #  The singleton instance  object returned will use the default values  for its attributes
-  #
-  #  @example Passing values of `:apikey` and `:connect_timeout`
-  #    TwelvedataRuby.client(apikey: "my-twelvedata-apikey", connect_timeout: 3000)
-  #
-  #  @example or, chain with other Client instance method
-  #    TwelvedataRuby.client(apikey: "my-twelvedata-apikey", connect_timeout: 3000).quote(symbol: "IBM")
-  #
-  #  In the last example, calling `#quote`, a valid API endpoint, an instance method with the same name
-  #  was dynamically defined and then fired up an API request to Twelvedata.
-  #
-  # @return [Client] singleton instance
-  def self.client(**options)
-    client = Client.instance
-    client.options = (client.options || {}).merge(options)
-    client
+    # Returns the current version
+    #
+    # @return [String] Version string
+    def version
+      VERSION
+    end
   end
 end