Enhance SerpApiError, update usage

Author: Ron Dahlgren

lib/serpapi/client.rb

@@ -234,12 +234,31 @@ def get(endpoint, decoder = :json, params = {})
           # parse JSON response with Ruby standard library
           data = JSON.parse(response.body, symbolize_names: symbolize_names)
           if data.instance_of?(Hash) && data.key?(:error)
-            raise SerpApiError, "HTTP request failed with error: #{data[:error]} from url: https://#{BACKEND}#{endpoint}, params: #{params}, decoder: #{decoder}, response status: #{response.status} "
+            raise SerpApiError.new("HTTP request failed with error: #{data[:error]} from url: " +
+                                   "https://#{BACKEND}#{endpoint}, params: #{params}, decoder: " +
+                                   "#{decoder}, response status: #{response.status}",
+                                   serpapi_error: data[:error],
+                                   search_params: params,
+                                   response_status: response.status,
+                                   search_id: data.dig(:search_metadata, :id),
+                                   decoder: decoder)
           elsif response.status != 200
-            raise SerpApiError, "HTTP request failed with response status: #{response.status} reponse: #{data} on get url: https://#{BACKEND}#{endpoint}, params: #{params}, decoder: #{decoder}"
+            raise SerpApiError.new("HTTP request failed with response status: #{response.status} " +
+                                   " reponse: #{data} on get url: https://#{BACKEND}#{endpoint}, " +
+                                   "params: #{params}, decoder: #{decoder}",
+                                   serpapi_error: data[:error],
+                                   search_params: params,
+                                   response_status: response.status,
+                                   search_id: data.dig(:search_metadata, :id),
+                                   decoder: decoder)
           end
         rescue JSON::ParserError
-          raise SerpApiError, "JSON parse error: #{response.body} on get url: https://#{BACKEND}#{endpoint}, params: #{params}, decoder: #{decoder}, response status: #{response.status}"
+            raise SerpApiError.new("JSON parse error: #{response.body} on get url: " +
+                                   "https://#{BACKEND}#{endpoint}, params: #{params}, " +
+                                   "decoder: #{decoder}, response status: #{response.status}",
+                                   search_params: params,
+                                   response_status: response.status,
+                                   decoder: decoder)
         end
 
         # discard response body
@@ -249,7 +268,12 @@ def get(endpoint, decoder = :json, params = {})
       when :html
         # html decoder
         if response.status != 200
-          raise SerpApiError, "HTTP request failed with response status: #{response.status} reponse: #{data} on get url: https://#{BACKEND}#{endpoint}, params: #{params}, decoder: #{decoder}"
+          raise SerpApiError.new("HTTP request failed with response status: #{response.status} " +
+                                 "reponse: #{data} on get url: https://#{BACKEND}#{endpoint}, " +
+                                 "params: #{params}, decoder: #{decoder}",
+                                search_params: params,
+                                response_status: response.status,
+                                decoder: decoder)
         end
 
         response.body

lib/serpapi/error.rb

@@ -2,13 +2,77 @@
 # frozen_string_literal: true
 
 module SerpApi
-  # SerpApiError wraps any errors related to the SerpApi client.
-  class SerpApiError < StandardError
-    # List the specific types of errors handled by the Error class.
-    #  - HTTP response errors from SerpApi.com
-    #  - Missing API key
-    #  - Credit limit
-    #  - Incorrect query
-    #  - more ...
+  class Error < StandardError
+    attr_reader :serpapi_error, :search_params, :response_status, :search_id, :decoder
+
+    # All attributes are optional keyword arguments.
+    #
+    # @param message [String, nil] an optional human message passed to StandardError
+    # @param serpapi_error [String, nil] optional error string coming from SerpAPI
+    # @param search_params [Hash, nil] optional hash of the search parameters used
+    # @param response_status [Integer, nil] optional HTTP or response status code
+    # @param search_id [String, nil] optional id returned by the service for the search
+    # @param decoder [String, nil] optional decoder/format used (e.g. "json")
+    def initialize(message = nil,
+                   serpapi_error: nil,
+                   search_params: nil,
+                   response_status: nil,
+                   search_id: nil,
+                   decoder: nil)
+      super(message)
+
+      @serpapi_error = validate_optional_string(serpapi_error, :serpapi_error)
+      @search_params  = freeze_hash(search_params)
+      @response_status = validate_optional_integer(response_status, :response_status)
+      @search_id = validate_optional_string(search_id, :search_id)
+      @decoder = validate_optional_string(decoder, :decoder)
+    end
+
+    # Return a compact hash representation (omits nil values).
+    #
+    # @return [Hash]
+    def to_h
+      {
+        message: message,
+        serpapi_error: serpapi_error,
+        search_params: search_params,
+        response_status: response_status,
+        search_id: search_id,
+        decoder: decoder
+      }.compact
+    end
+
+    private
+
+    def validate_optional_string(value, name = nil)
+      return nil if value.nil?
+      unless value.is_a?(String)
+        raise TypeError, "expected #{name || 'value'} to be a String, got #{value.class}"
+      end
+
+      value.freeze
+    end
+
+    def validate_optional_integer(value, name = nil)
+      return nil if value.nil?
+      return value if value.is_a?(Integer)
+
+      # Accept numeric-like strings (e.g. "200") by converting; fail otherwise.
+      begin
+        Integer(value)
+      rescue ArgumentError, TypeError
+        raise TypeError, "expected #{name || 'value'} to be an Integer (or integer-like), got #{value.inspect}"
+      end
+    end
+
+    def freeze_hash(value)
+      return nil if value.nil?
+      unless value.is_a?(Hash)
+        raise TypeError, "expected search_params to be a Hash, got #{value.class}"
+      end
+
+      # duplicate and freeze to avoid accidental external mutation
+      value.dup.freeze
+    end
   end
 end

spec/serpapi/client/client_spec.rb

@@ -134,6 +134,8 @@
     expect { client.search(q: 'Invalid Query') }.to raise_error(SerpApi::SerpApiError)
   end
 
+
+
 end
 
 describe 'SerpApi client with persitency disabled' do