rospatent 1.1.0 → 1.3.0

data/lib/generators/rospatent/install/templates/initializer.rb

@@ -3,22 +3,46 @@
 # Rospatent API client configuration
 # Documentation: https://online.rospatent.gov.ru/open-data/open-api
 Rospatent.configure do |config|
-  # API URL (default: https://searchplatform.rospatent.gov.ru)
-  # config.api_url = ENV.fetch("ROSPATENT_API_URL", "https://searchplatform.rospatent.gov.ru")
-
   # JWT Bearer token for API authorization - REQUIRED
-  # Obtain this from the Rospatent API administration
-  config.token = Rails.application.credentials.rospatent_api_token || ENV.fetch(
-    "ROSPATENT_API_TOKEN", nil
-  )
+  # Priority: Rails credentials > Environment variable > Manual setting
+  config.token = Rails.application.credentials.rospatent_token ||
+                 ENV["ROSPATENT_TOKEN"] ||
+                 ENV.fetch("ROSPATENT_API_TOKEN", nil)
+
+  # Environment configuration - respect environment variables
+  config.environment = ENV.fetch("ROSPATENT_ENV", Rails.env)
+
+  # Cache configuration - respect environment variables or use Rails defaults
+  config.cache_enabled = if ENV.key?("ROSPATENT_CACHE_ENABLED")
+                           ENV["ROSPATENT_CACHE_ENABLED"] == "true"
+                         else
+                           Rails.env.production?
+                         end
 
-  # Rails-specific environment integration
-  config.environment = Rails.env
-  config.cache_enabled = Rails.env.production?
-  config.log_level = Rails.env.production? ? :warn : :debug
+  # Logging configuration - CRITICAL: Respect environment variables first!
+  config.log_level = if ENV.key?("ROSPATENT_LOG_LEVEL")
+                       ENV["ROSPATENT_LOG_LEVEL"].to_sym
+                     else
+                       Rails.env.production? ? :warn : :debug
+                     end
 
-  # Optional: Override defaults if needed
-  # config.timeout = 30
-  # config.retry_count = 3
-  # config.user_agent = "YourApp/1.0"
+  config.log_requests = if ENV.key?("ROSPATENT_LOG_REQUESTS")
+                          ENV["ROSPATENT_LOG_REQUESTS"] == "true"
+                        else
+                          !Rails.env.production?
+                        end
+
+  config.log_responses = if ENV.key?("ROSPATENT_LOG_RESPONSES")
+                           ENV["ROSPATENT_LOG_RESPONSES"] == "true"
+                         else
+                           Rails.env.development?
+                         end
+
+  # Optional: Override other defaults if needed
+  # config.api_url = ENV.fetch("ROSPATENT_API_URL", "https://searchplatform.rospatent.gov.ru")
+  # config.timeout = ENV.fetch("ROSPATENT_TIMEOUT", "30").to_i
+  # config.retry_count = ENV.fetch("ROSPATENT_RETRY_COUNT", "3").to_i
+  # config.cache_ttl = ENV.fetch("ROSPATENT_CACHE_TTL", "300").to_i
+  # config.cache_max_size = ENV.fetch("ROSPATENT_CACHE_MAX_SIZE", "1000").to_i
+  # config.connection_pool_size = ENV.fetch("ROSPATENT_POOL_SIZE", "5").to_i
 end

data/lib/rospatent/client.rb

@@ -150,7 +150,7 @@ module Rospatent
     # @param text [String] The text to find similar patents to (minimum 50 words required)
     # @param count [Integer] Maximum number of results to return (default: 100)
     # @return [Hash] The similar search results
-    # @raise [Rospatent::Errors::ValidationError] If text has insufficient words or other validation errors
+    # @raise [Rospatent::Errors::ValidationError] If text has insufficient words or errors
     def similar_patents_by_text(text, count: 100)
       # Validate inputs - text must have at least 50 words for the API
       validated_text = validate_text_with_word_count(text, "search_text", min_words: 50,
@@ -199,7 +199,7 @@ module Rospatent
       @logger.log_cache("miss", cache_key)
 
       # Make the API request
-      result = get("/patsearch/v0.2/datasets/tree")
+      result = get("/patsearch/v0.2/datasets/tree", {})
 
       # Cache the result for longer since datasets don't change often
       @cache.set(cache_key, result, ttl: 3600) # Cache for 1 hour
@@ -230,19 +230,22 @@ module Rospatent
       # Format publication date
       formatted_date = validated_date.strftime("%Y/%m/%d")
 
+      # Format publication number with appropriate padding
+      formatted_number = format_publication_number(validated_number, validated_country)
+
       # Construct the path
       path = "/media/#{validated_collection}/#{validated_country}/" \
-             "#{validated_doc_type}/#{formatted_date}/#{validated_number}/" \
+             "#{validated_doc_type}/#{formatted_date}/#{formatted_number}/" \
              "#{validated_filename}"
 
-      # Make a GET request to retrieve the media file
-      get(path)
+      # Get binary data
+      get(path, {}, binary: true)
     end
 
-    # Simplified method to retrieve media data by patent ID and collection ID
-    # @param document_id [String] The patent document ID (e.g., "RU134694U1_20131120")
-    # @param collection_id [String] Dataset/collection identifier (e.g., "National")
-    # @param filename [String] Media file name (e.g., "document.pdf")
+    # Retrieve media using simplified patent ID format
+    # @param document_id [String] Patent document ID (e.g., "RU134694U1_20131120")
+    # @param collection_id [String] Collection identifier (e.g., "National")
+    # @param filename [String] Filename to retrieve (e.g., "document.pdf")
     # @return [String] Binary content of the requested file
     # @raise [Rospatent::Errors::InvalidRequestError] If document_id format is invalid
     #   or parameters are missing
@@ -258,9 +261,12 @@ module Rospatent
       # Format the date from YYYYMMDD to YYYY/MM/DD
       formatted_date = id_parts[:date].gsub(/^(\d{4})(\d{2})(\d{2})$/, '\1/\2/\3')
 
+      # Format publication number with appropriate padding
+      formatted_number = format_publication_number(id_parts[:number], id_parts[:country_code])
+
       # Call the base method with extracted components
       patent_media(validated_collection, id_parts[:country_code], id_parts[:doc_type],
-                   formatted_date, id_parts[:number], validated_filename)
+                   formatted_date, formatted_number, validated_filename)
     end
 
     # Extract and parse the abstract content from a patent document
@@ -334,7 +340,7 @@ module Rospatent
       }
 
       # Make a POST request to the classification search endpoint
-      result = post("/patsearch/v0.2/classification/#{validated_classifier}/search", payload)
+      result = post("/patsearch/v0.2/classification/#{validated_classifier}/search/", payload)
 
       # Cache the result
       @cache.set(cache_key, result, ttl: 1800) # Cache for 30 minutes
@@ -374,7 +380,7 @@ module Rospatent
       }
 
       # Make a POST request to the classification code endpoint
-      result = post("/patsearch/v0.2/classification/#{validated_classifier}/code", payload)
+      result = post("/patsearch/v0.2/classification/#{validated_classifier}/code/", payload)
 
       # Cache the result for longer since classification codes don't change often
       @cache.set(cache_key, result, ttl: 3600) # Cache for 1 hour
@@ -386,8 +392,9 @@ module Rospatent
     # Execute a GET request to the API
     # @param endpoint [String] API endpoint
     # @param params [Hash] Query parameters (optional)
-    # @return [Hash] Response data
-    def get(endpoint, params = {})
+    # @param binary [Boolean] Whether to expect binary response (default: false)
+    # @return [Hash, String] Response data (Hash for JSON, String for binary)
+    def get(endpoint, params = {}, binary: false)
       start_time = Time.now
       request_id = generate_request_id
 
@@ -395,8 +402,12 @@ module Rospatent
       @request_count += 1
 
       response = connection.get(endpoint, params) do |req|
-        req.headers["Accept"] = "application/json"
-        req.headers["Content-Type"] = "application/json"
+        if binary
+          req.headers["Accept"] = "*/*"
+        else
+          req.headers["Accept"] = "application/json"
+          req.headers["Content-Type"] = "application/json"
+        end
         req.headers["X-Request-ID"] = request_id
       end
 
@@ -406,7 +417,11 @@ module Rospatent
       @logger.log_response("GET", endpoint, response.status, duration,
                            response_size: response.body&.bytesize, request_id: request_id)
 
-      handle_response(response, request_id)
+      if binary
+        handle_binary_response(response, request_id)
+      else
+        handle_response(response, request_id)
+      end
     rescue Faraday::Error => e
       @logger.log_error(e, { endpoint: endpoint, params: params, request_id: request_id })
       handle_error(e)
@@ -492,12 +507,13 @@ module Rospatent
         qn: { type: :string, max_length: 1000 },
         limit: { type: :positive_integer, min_value: 1, max_value: 100 },
         offset: { type: :positive_integer, min_value: 0, max_value: 10_000 },
-        pre_tag: { type: :string, max_length: 50 },
-        post_tag: { type: :string, max_length: 50 },
+        pre_tag: { type: :string_or_array, max_length: 50, max_size: 10 },
+        post_tag: { type: :string_or_array, max_length: 50, max_size: 10 },
         sort: { type: :enum, allowed_values: %i[relevance pub_date filing_date] },
-        group_by: { type: :enum, allowed_values: [:patent_family] },
+        group_by: { type: :string_enum, allowed_values: %w[family:docdb family:dwpi] },
         include_facets: { type: :boolean },
-        highlight: { type: :boolean },
+        highlight: { type: :hash },
+        filter: { type: :filter },
         datasets: { type: :array, max_size: 10 }
       }
 
@@ -617,7 +633,8 @@ module Rospatent
 
       error_msg = begin
         data = JSON.parse(response.body)
-        data["error"] || data["message"] || "Unknown error"
+        # Try different possible error message fields used by Rospatent API
+        data["result"] || data["error"] || data["message"] || "Unknown error"
       rescue JSON::ParserError
         response.body
       end
@@ -642,6 +659,43 @@ module Rospatent
       end
     end
 
+    # Process binary API response (for media files)
+    # @param response [Faraday::Response] Raw response from the API
+    # @param request_id [String] Request ID for tracking
+    # @return [String] Binary response data
+    # @raise [Rospatent::Errors::ApiError] If the response is not successful
+    def handle_binary_response(response, request_id = nil)
+      return response.body if response.success?
+
+      # For binary endpoints, error responses might still be JSON
+      error_msg = begin
+        data = JSON.parse(response.body)
+        # Try different possible error message fields used by Rospatent API
+        data["result"] || data["error"] || data["message"] || "Unknown error"
+      rescue JSON::ParserError
+        "Binary request failed"
+      end
+
+      # Create specific error types based on status code
+      case response.status
+      when 401
+        raise Errors::AuthenticationError, "#{error_msg} [Request ID: #{request_id}]"
+      when 404
+        raise Errors::NotFoundError.new("#{error_msg} [Request ID: #{request_id}]", response.status)
+      when 422
+        errors = extract_validation_errors(response)
+        raise Errors::ValidationError.new(error_msg, errors)
+      when 429
+        retry_after = response.headers["Retry-After"]&.to_i
+        raise Errors::RateLimitError.new(error_msg, response.status, retry_after)
+      when 503
+        raise Errors::ServiceUnavailableError.new("#{error_msg} [Request ID: #{request_id}]",
+                                                  response.status)
+      else
+        raise Errors::ApiError.new(error_msg, response.status, response.body, request_id)
+      end
+    end
+
     # Handle connection errors
     # @param error [Faraday::Error] Connection error
     # @raise [Rospatent::Errors::ConnectionError] Wrapped connection error
@@ -661,7 +715,8 @@ module Rospatent
     # @return [Hash] Field-specific validation errors
     def extract_validation_errors(response)
       data = JSON.parse(response.body)
-      data["errors"] || data["validation_errors"] || {}
+      # Check various possible validation error fields
+      data["errors"] || data["validation_errors"] || data["details"] || {}
     rescue JSON::ParserError
       {}
     end
@@ -695,5 +750,18 @@ module Rospatent
     def generate_request_id
       "req_#{Time.now.to_f}_#{rand(10_000)}"
     end
+
+    # Pad publication number with leading zeros for specific countries
+    # @param number [String] Publication number to pad
+    # @param country_code [String] Country code (e.g., "RU")
+    # @return [String] Padded publication number
+    def format_publication_number(number, country_code)
+      # Russian patents require 10-digit publication numbers
+      if country_code == "RU" && number.length < 10
+        number.rjust(10, "0")
+      else
+        number
+      end
+    end
   end
 end

data/lib/rospatent/configuration.rb

@@ -31,7 +31,7 @@ module Rospatent
     # Initialize a new configuration with default values
     def initialize
       @api_url = "https://searchplatform.rospatent.gov.ru"
-      @token = nil
+      @token = ENV["ROSPATENT_TOKEN"] || ENV.fetch("ROSPATENT_API_TOKEN", nil)
       @timeout = 30
       @retry_count = 3
       @user_agent = "Rospatent Ruby Client/#{Rospatent::VERSION}"
@@ -106,6 +106,7 @@ module Rospatent
     private
 
     # Load environment-specific configuration
+    # Only override values that weren't explicitly set by environment variables
     def load_environment_config
       unless valid_environment?
         raise ArgumentError, "Invalid environment: #{@environment}. " \
@@ -116,20 +117,20 @@ module Rospatent
       when "production"
         @timeout = 60
         @retry_count = 5
-        @log_level = :warn
-        @cache_ttl = 600 # 10 minutes in production
+        @log_level = :warn unless ENV.key?("ROSPATENT_LOG_LEVEL")
+        @cache_ttl = 600 unless ENV.key?("ROSPATENT_CACHE_TTL") # 10 minutes in production
       when "staging"
         @timeout = 45
         @retry_count = 3
-        @log_level = :info
-        @cache_ttl = 300 # 5 minutes in staging
+        @log_level = :info unless ENV.key?("ROSPATENT_LOG_LEVEL")
+        @cache_ttl = 300 unless ENV.key?("ROSPATENT_CACHE_TTL") # 5 minutes in staging
       when "development"
         @timeout = 10
         @retry_count = 1
-        @log_level = :debug
-        @log_requests = true
-        @log_responses = true
-        @cache_ttl = 60 # 1 minute in development
+        @log_level = :debug unless ENV.key?("ROSPATENT_LOG_LEVEL")
+        @log_requests = true unless ENV.key?("ROSPATENT_LOG_REQUESTS")
+        @log_responses = true unless ENV.key?("ROSPATENT_LOG_RESPONSES")
+        @cache_ttl = 60 unless ENV.key?("ROSPATENT_CACHE_TTL") # 1 minute in development
       end
     end
   end

data/lib/rospatent/input_validator.rb

@@ -170,6 +170,26 @@ module Rospatent
       value
     end
 
+    # Validate string enum value (preserves string type)
+    # @param value [String, nil] Value to validate
+    # @param allowed_values [Array<String>] Array of allowed string values
+    # @param field_name [String] Name of the field for error messages
+    # @return [String] Validated string
+    # @raise [ValidationError] If value is not in allowed list
+    def validate_string_enum(value, allowed_values, field_name)
+      return nil if value.nil?
+
+      # Ensure value is a string
+      value = value.to_s if value.respond_to?(:to_s)
+
+      unless allowed_values.include?(value)
+        raise Errors::ValidationError,
+              "Invalid #{field_name}. Allowed values: #{allowed_values.join(', ')}"
+      end
+
+      value
+    end
+
     # Validate array parameter
     # @param value [Array, nil] Array to validate
     # @param field_name [String] Name of the field for error messages
@@ -207,6 +227,29 @@ module Rospatent
       value
     end
 
+    # Validate string or array parameter (for highlight tags)
+    # @param value [String, Array, nil] String or Array to validate
+    # @param field_name [String] Name of the field for error messages
+    # @param max_length [Integer, nil] Maximum string length (for string values)
+    # @param max_size [Integer, nil] Maximum array size (for array values)
+    # @return [String, Array] Validated string or array
+    # @raise [ValidationError] If value is invalid
+    def validate_string_or_array(value, field_name, max_length: nil, max_size: nil)
+      return nil if value.nil?
+
+      case value
+      when String
+        validate_string(value, field_name, max_length: max_length)
+      when Array
+        validate_array(value, field_name, max_size: max_size) do |element|
+          validate_string(element, "#{field_name} element", max_length: max_length)
+        end
+      else
+        raise Errors::ValidationError,
+              "Invalid #{field_name} type. Expected String or Array, got #{value.class}"
+      end
+    end
+
     # Validate hash parameter
     # @param value [Hash, nil] Hash to validate
     # @param field_name [String] Name of the field for error messages
@@ -296,8 +339,17 @@ module Rospatent
                                     param_name.to_s,
                                     max_length: rules[:max_length]
                                   )
+                                when :string_or_array
+                                  validate_string_or_array(
+                                    value,
+                                    param_name.to_s,
+                                    max_length: rules[:max_length],
+                                    max_size: rules[:max_size]
+                                  )
                                 when :enum
                                   validate_enum(value, rules[:allowed_values], param_name.to_s)
+                                when :string_enum
+                                  validate_string_enum(value, rules[:allowed_values], param_name.to_s)
                                 when :date
                                   validate_date(value, param_name.to_s)
                                 when :array
@@ -314,6 +366,11 @@ module Rospatent
                                     required_keys: rules[:required_keys] || [],
                                     allowed_keys: rules[:allowed_keys]
                                   )
+                                when :filter
+                                  validate_filter(value, param_name.to_s)
+                                when :boolean
+                                  # Convert to boolean, nil values remain nil
+                                  value.nil? ? nil : !!value
                                 else
                                   value
                                 end
@@ -334,5 +391,183 @@ module Rospatent
     def count_words(text)
       text.split.size
     end
+
+    # Validate filter parameter according to Rospatent API specification
+    # @param filter [Hash, nil] Filter hash to validate
+    # @param field_name [String] Name of the field for error messages
+    # @return [Hash] Validated filter hash
+    # @raise [ValidationError] If filter structure is invalid
+    def validate_filter(filter, field_name = "filter")
+      return nil if filter.nil?
+
+      unless filter.is_a?(Hash)
+        raise Errors::ValidationError,
+              "Invalid #{field_name} type. Expected Hash, got #{filter.class}"
+      end
+
+      validated_filter = {}
+
+      filter.each do |filter_field, filter_value|
+        case filter_field.to_s
+        when "authors", "patent_holders", "country", "kind", "ids",
+             "classification.ipc", "classification.ipc_group", "classification.ipc_subclass",
+             "classification.cpc", "classification.cpc_group", "classification.cpc_subclass"
+          # These fields use {"values": [...]} format
+          validated_filter[filter_field] = validate_filter_values(filter_value, filter_field)
+        when "date_published", "application.filing_date"
+          # These fields use {"range": {"gt": "20000101"}} format
+          validated_filter[filter_field] = validate_filter_range(filter_value, filter_field)
+        else
+          raise Errors::ValidationError,
+                "Invalid filter field '#{filter_field}'. Allowed fields: authors, patent_holders, " \
+                "country, kind, ids, date_published, application.filing_date, classification.ipc, " \
+                "classification.ipc_group, classification.ipc_subclass, classification.cpc, " \
+                "classification.cpc_group, classification.cpc_subclass"
+        end
+      end
+
+      validated_filter
+    end
+
+    # Validate filter values structure (for list-based filters)
+    # @param filter_value [Hash] Filter value to validate
+    # @param filter_field [String] Filter field name for error messages
+    # @return [Hash] Validated filter value
+    # @raise [ValidationError] If structure is invalid
+    def validate_filter_values(filter_value, filter_field)
+      unless filter_value.is_a?(Hash)
+        raise Errors::ValidationError,
+              "Invalid #{filter_field} filter structure. Expected Hash with 'values' key, got #{filter_value.class}"
+      end
+
+      unless filter_value.key?("values") || filter_value.key?(:values)
+        raise Errors::ValidationError,
+              "Missing required 'values' key in #{filter_field} filter. Expected format: {\"values\": [...]}"
+      end
+
+      values = filter_value["values"] || filter_value[:values]
+
+      unless values.is_a?(Array)
+        raise Errors::ValidationError,
+              "Invalid 'values' type in #{filter_field} filter. Expected Array, got #{values.class}"
+      end
+
+      if values.empty?
+        raise Errors::ValidationError,
+              "Empty 'values' array in #{filter_field} filter. At least one value must be provided"
+      end
+
+      # Validate each value is a string
+      values.each_with_index do |value, index|
+        unless value.is_a?(String) || value.is_a?(Symbol)
+          raise Errors::ValidationError,
+                "Invalid value type at index #{index} in #{filter_field} filter. Expected String, got #{value.class}"
+        end
+      end
+
+      { "values" => values.map(&:to_s) }
+    end
+
+    # Validate filter range structure (for date-based filters)
+    # @param filter_value [Hash] Filter value to validate
+    # @param filter_field [String] Filter field name for error messages
+    # @return [Hash] Validated filter value
+    # @raise [ValidationError] If structure is invalid
+    def validate_filter_range(filter_value, filter_field)
+      unless filter_value.is_a?(Hash)
+        raise Errors::ValidationError,
+              "Invalid #{filter_field} filter structure. Expected Hash with 'range' key, got #{filter_value.class}"
+      end
+
+      unless filter_value.key?("range") || filter_value.key?(:range)
+        raise Errors::ValidationError,
+              "Missing required 'range' key in #{filter_field} filter. Expected format: {\"range\": {\"gt\": \"20000101\"}}"
+      end
+
+      range = filter_value["range"] || filter_value[:range]
+
+      unless range.is_a?(Hash)
+        raise Errors::ValidationError,
+              "Invalid 'range' type in #{filter_field} filter. Expected Hash, got #{range.class}"
+      end
+
+      # Allowed range operators
+      allowed_operators = %w[gt gte lt lte]
+      validated_range = {}
+
+      if range.empty?
+        raise Errors::ValidationError,
+              "Empty 'range' object in #{filter_field} filter. At least one operator (gt, gte, lt, lte) must be provided"
+      end
+
+      range.each do |operator, value|
+        operator_str = operator.to_s
+
+        unless allowed_operators.include?(operator_str)
+          raise Errors::ValidationError,
+                "Invalid range operator '#{operator_str}' in #{filter_field} filter. " \
+                "Allowed operators: #{allowed_operators.join(', ')}"
+        end
+
+        # Validate date format (YYYYMMDD)
+        validated_date = validate_filter_date(value, filter_field, operator_str)
+        validated_range[operator_str] = validated_date
+      end
+
+      { "range" => validated_range }
+    end
+
+    # Validate date format for filter ranges
+    # @param date_value [String, Date] Date value to validate
+    # @param filter_field [String] Filter field name for error messages
+    # @param operator [String] Range operator for error messages
+    # @return [String] Validated date in YYYYMMDD format
+    # @raise [ValidationError] If date format is invalid
+    def validate_filter_date(date_value, filter_field, operator)
+      # Convert Date objects to string
+      return date_value.strftime("%Y%m%d") if date_value.is_a?(Date)
+
+      unless date_value.is_a?(String)
+        raise Errors::ValidationError,
+              "Invalid date type for '#{operator}' in #{filter_field} filter. Expected String or Date, got #{date_value.class}"
+      end
+
+      # Check if it's already in YYYYMMDD format
+      if date_value.match?(/^\d{8}$/)
+        # Validate that it's a real date
+        begin
+          year = date_value[0..3].to_i
+          month = date_value[4..5].to_i
+          day = date_value[6..7].to_i
+          Date.new(year, month, day)
+          return date_value
+        rescue ArgumentError
+          raise Errors::ValidationError,
+                "Invalid date '#{date_value}' for '#{operator}' in #{filter_field} filter. Not a valid date"
+        end
+      end
+
+      # Try to parse various date formats and convert to YYYYMMDD
+      begin
+        parsed_date = case date_value
+                      when /^\d{4}-\d{2}-\d{2}$/ # YYYY-MM-DD
+                        Date.parse(date_value)
+                      when %r{^\d{4}/\d{2}/\d{2}$}  # YYYY/MM/DD
+                        Date.parse(date_value)
+                      when %r{^\d{2}/\d{2}/\d{4}$}  # MM/DD/YYYY
+                        Date.strptime(date_value, "%m/%d/%Y")
+                      when /^\d{2}-\d{2}-\d{4}$/ # MM-DD-YYYY
+                        Date.strptime(date_value, "%m-%d-%Y")
+                      else
+                        Date.parse(date_value) # Let Date.parse try to handle it
+                      end
+
+        parsed_date.strftime("%Y%m%d")
+      rescue ArgumentError
+        raise Errors::ValidationError,
+              "Invalid date format '#{date_value}' for '#{operator}' in #{filter_field} filter. " \
+              "Expected YYYYMMDD format (e.g., '20200101') or standard date formats (YYYY-MM-DD, etc.)"
+      end
+    end
   end
 end