rospatent 1.0.0

data/lib/rospatent/logger.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require "logger"
+require "json"
+require "time"
+
+module Rospatent
+  # Structured logger for API requests, responses, and events
+  class Logger
+    LEVELS = {
+      debug: ::Logger::DEBUG,
+      info: ::Logger::INFO,
+      warn: ::Logger::WARN,
+      error: ::Logger::ERROR,
+      fatal: ::Logger::FATAL
+    }.freeze
+
+    attr_reader :logger, :level
+
+    # Initialize a new logger
+    # @param output [IO, String] Output destination (STDOUT, file path, etc.)
+    # @param level [Symbol] Log level (:debug, :info, :warn, :error, :fatal)
+    # @param formatter [Symbol] Log format (:json, :text)
+    def initialize(output: $stdout, level: :info, formatter: :text)
+      @logger = ::Logger.new(output)
+      @level = level
+      @logger.level = LEVELS[level] || ::Logger::INFO
+
+      @logger.formatter = case formatter
+                          when :json
+                            method(:json_formatter)
+                          else
+                            method(:text_formatter)
+                          end
+    end
+
+    # Log an API request
+    # @param method [String] HTTP method
+    # @param endpoint [String] API endpoint
+    # @param params [Hash] Request parameters
+    # @param headers [Hash] Request headers (optional)
+    def log_request(method, endpoint, params = {}, headers = {})
+      return unless should_log?(:info)
+
+      safe_params = sanitize_params(params)
+      safe_headers = sanitize_headers(headers)
+
+      log_structured(:info, "API Request", {
+                       http_method: method.upcase,
+                       endpoint: endpoint,
+                       params: safe_params,
+                       headers: safe_headers,
+                       timestamp: Time.now.iso8601,
+                       request_id: generate_request_id
+                     })
+    end
+
+    # Log an API response
+    # @param method [String] HTTP method
+    # @param endpoint [String] API endpoint
+    # @param status [Integer] Response status code
+    # @param duration [Float] Request duration in seconds
+    # @param response_size [Integer] Response body size (optional)
+    # @param request_id [String] Request ID for correlation
+    def log_response(method, endpoint, status, duration, response_size: nil, request_id: nil)
+      return unless should_log?(:info)
+
+      level = status >= 400 ? :warn : :info
+
+      log_structured(level, "API Response", {
+                       http_method: method.upcase,
+                       endpoint: endpoint,
+                       status_code: status,
+                       duration_ms: (duration * 1000).round(2),
+                       response_size_bytes: response_size,
+                       timestamp: Time.now.iso8601,
+                       request_id: request_id
+                     })
+    end
+
+    # Log an error with context
+    # @param error [Exception] The error object
+    # @param context [Hash] Additional context information
+    def log_error(error, context = {})
+      log_structured(:error, "Error occurred", {
+                       error_class: error.class.name,
+                       error_message: error.message,
+                       error_backtrace: error.backtrace&.first(10),
+                       context: context,
+                       timestamp: Time.now.iso8601
+                     })
+    end
+
+    # Log cache operations
+    # @param operation [String] Cache operation (hit, miss, set, delete)
+    # @param key [String] Cache key
+    # @param ttl [Integer] Time to live (for set operations)
+    def log_cache(operation, key, ttl: nil)
+      return unless should_log?(:debug)
+
+      log_structured(:debug, "Cache operation", {
+                       operation: operation,
+                       cache_key: key,
+                       ttl_seconds: ttl,
+                       timestamp: Time.now.iso8601
+                     })
+    end
+
+    # Log performance metrics
+    # @param operation [String] Operation name
+    # @param duration [Float] Duration in seconds
+    # @param metadata [Hash] Additional metadata
+    def log_performance(operation, duration, metadata = {})
+      return unless should_log?(:info)
+
+      log_structured(:info, "Performance metric", {
+                       operation: operation,
+                       duration_ms: (duration * 1000).round(2),
+                       metadata: metadata,
+                       timestamp: Time.now.iso8601
+                     })
+    end
+
+    # Log debug information
+    # @param message [String] Debug message
+    # @param data [Hash] Additional debug data
+    def debug(message, data = {})
+      log_structured(:debug, message, data)
+    end
+
+    # Log info message
+    # @param message [String] Info message
+    # @param data [Hash] Additional data
+    def info(message, data = {})
+      log_structured(:info, message, data)
+    end
+
+    # Log warning
+    # @param message [String] Warning message
+    # @param data [Hash] Additional data
+    def warn(message, data = {})
+      log_structured(:warn, message, data)
+    end
+
+    # Log error message
+    # @param message [String] Error message
+    # @param data [Hash] Additional data
+    def error(message, data = {})
+      log_structured(:error, message, data)
+    end
+
+    # Log fatal error
+    # @param message [String] Fatal error message
+    # @param data [Hash] Additional data
+    def fatal(message, data = {})
+      log_structured(:fatal, message, data)
+    end
+
+    private
+
+    # Check if we should log at the given level
+    # @param level [Symbol] Log level to check
+    # @return [Boolean] true if should log
+    def should_log?(level)
+      LEVELS[level] >= @logger.level
+    end
+
+    # Log structured data
+    # @param level [Symbol] Log level
+    # @param message [String] Log message
+    # @param data [Hash] Structured data
+    def log_structured(level, message, data = {})
+      return unless should_log?(level)
+
+      log_data = {
+        message: message,
+        level: level.to_s.upcase,
+        gem: "rospatent",
+        version: Rospatent::VERSION
+      }.merge(data)
+
+      @logger.send(level, log_data)
+    end
+
+    # Sanitize request parameters to remove sensitive data
+    # @param params [Hash] Request parameters
+    # @return [Hash] Sanitized parameters
+    def sanitize_params(params)
+      return {} unless params.is_a?(Hash)
+
+      sanitized = params.dup
+      sensitive_keys = %w[token password secret key auth authorization]
+
+      sensitive_keys.each do |key|
+        sanitized.each do |param_key, _value|
+          sanitized[param_key] = "[REDACTED]" if param_key.to_s.downcase.include?(key.downcase)
+        end
+      end
+
+      sanitized
+    end
+
+    # Sanitize headers to remove sensitive data
+    # @param headers [Hash] Request headers
+    # @return [Hash] Sanitized headers
+    def sanitize_headers(headers)
+      return {} unless headers.is_a?(Hash)
+
+      sanitized = headers.dup
+      sensitive_headers = %w[authorization x-api-key x-auth-token bearer]
+
+      sensitive_headers.each do |header|
+        sanitized.each do |header_key, _value|
+          sanitized[header_key] = "[REDACTED]" if header_key.to_s.downcase.include?(header.downcase)
+        end
+      end
+
+      sanitized
+    end
+
+    # Generate a unique request ID
+    # @return [String] Unique request identifier
+    def generate_request_id
+      "req_#{Time.now.to_f}_#{rand(10_000)}"
+    end
+
+    # JSON formatter for structured logging
+    # @param severity [String] Log severity
+    # @param datetime [Time] Log timestamp
+    # @param progname [String] Program name
+    # @param msg [Object] Log message/data
+    # @return [String] Formatted log entry
+    def json_formatter(severity, datetime, progname, msg)
+      log_entry = if msg.is_a?(Hash)
+                    msg.merge(
+                      severity: severity,
+                      datetime: datetime.iso8601,
+                      progname: progname
+                    )
+                  else
+                    {
+                      severity: severity,
+                      datetime: datetime.iso8601,
+                      progname: progname,
+                      message: msg.to_s
+                    }
+                  end
+
+      "#{JSON.generate(log_entry)}\n"
+    end
+
+    # Text formatter for human-readable logging
+    # @param severity [String] Log severity
+    # @param datetime [Time] Log timestamp
+    # @param progname [String] Program name
+    # @param msg [Object] Log message/data
+    # @return [String] Formatted log entry
+    def text_formatter(severity, datetime, progname, msg)
+      timestamp = datetime.strftime("%Y-%m-%d %H:%M:%S")
+
+      if msg.is_a?(Hash)
+        message = msg[:message] || "Structured log"
+        details = msg.except(:message).map { |k, v| "#{k}=#{v}" }.join(" ")
+        formatted_msg = details.empty? ? message : "#{message} (#{details})"
+      else
+        formatted_msg = msg.to_s
+      end
+
+      "[#{timestamp}] #{severity} -- #{progname}: #{formatted_msg}\n"
+    end
+  end
+
+  # Null logger implementation for when logging is disabled
+  class NullLogger
+    def log_request(*args); end
+    def log_response(*args); end
+    def log_error(*args); end
+    def log_cache(*args); end
+    def log_performance(*args); end
+    def debug(*args); end
+    def info(*args); end
+    def warn(*args); end
+    def error(*args); end
+    def fatal(*args); end
+  end
+end

data/lib/rospatent/patent_parser.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Rospatent
+  # Module for parsing patent documents' XML content into structured formats
+  module PatentParser
+    # Extract and parse the abstract content from a patent document
+    # @param patent_data [Hash] The patent document data returned by Client#patent method
+    # @param format [Symbol] The desired output format (:text or :html)
+    # @param language [String] The language code (e.g., "ru", "en")
+    # @return [String, nil] The parsed abstract content in the requested format or nil if not found
+    # @example Get plain text abstract
+    #   abstract = PatentParser.parse_abstract(patent_doc)
+    # @example Get HTML abstract in English
+    #   abstract_html = PatentParser.parse_abstract(patent_doc, format: :html, language: "en")
+    def self.parse_abstract(patent_data, format: :text, language: "ru")
+      return nil unless patent_data && patent_data["abstract"] && patent_data["abstract"][language]
+
+      abstract_xml = patent_data["abstract"][language]
+
+      case format
+      when :html
+        # Extract the inner HTML content
+        extract_inner_html(abstract_xml)
+      else
+        # Extract plain text
+        extract_text_content(abstract_xml)
+      end
+    end
+
+    # Extract and parse the description content from a patent document
+    # @param patent_data [Hash] The patent document data returned by Client#patent method
+    # @param format [Symbol] The desired output format (:text, :html, or :sections)
+    # @param language [String] The language code (e.g., "ru", "en")
+    # @return [String, Array, nil] The parsed description content in the requested format or nil if not found
+    # @example Get plain text description
+    #   description = PatentParser.parse_description(patent_doc)
+    # @example Get HTML description
+    #   description_html = PatentParser.parse_description(patent_doc, format: :html)
+    # @example Get description split into sections
+    #   sections = PatentParser.parse_description(patent_doc, format: :sections)
+    def self.parse_description(patent_data, format: :text, language: "ru")
+      unless patent_data && patent_data["description"] && patent_data["description"][language]
+        return nil
+      end
+
+      description_xml = patent_data["description"][language]
+
+      case format
+      when :html
+        # Extract the inner HTML content
+        extract_inner_html(description_xml)
+      when :sections
+        # Split the description into numbered sections
+        extract_description_sections(description_xml)
+      else
+        # Extract plain text
+        extract_text_content(description_xml)
+      end
+    end
+
+    class << self
+      private
+
+      # Extract plain text content from XML
+      # @param xml_content [String] XML content
+      # @return [String] Plain text content
+      def extract_text_content(xml_content)
+        # Remove XML tags and normalize whitespace
+        text = xml_content.gsub(/<[^>]*>/, " ")
+                          .gsub(/\s+/, " ")
+                          .strip
+
+        # Decode HTML entities
+        decode_html_entities(text)
+      end
+
+      # Extract inner HTML content from XML
+      # @param xml_content [String] XML content
+      # @return [String] HTML content
+      def extract_inner_html(xml_content)
+        # Find content inside the main div tags
+        if xml_content =~ %r{<div[^>]*>(.*)</div>}m
+          ::Regexp.last_match(1).strip
+        else
+          # Fallback: return everything between the root element tags
+          xml_content.sub(/^<[^>]*>/, "").sub(%r{</[^>]*>$}, "")
+        end
+      end
+
+      # Extract sections from description XML
+      # @param xml_content [String] XML description content
+      # @return [Array<Hash>] Array of section hashes with number and content
+      def extract_description_sections(xml_content)
+        sections = []
+
+        # Extract each div block which represents a section
+        xml_content.scan(%r{<div[^>]*>.*?</div>}m) do |div|
+          # Extract section number from the span tag
+          section_number = if div =~ %r{<span[^>]*>\[(\d+)\]</span>}
+                             ::Regexp.last_match(1).to_i
+                           else
+                             sections.size + 1
+                           end
+
+          # Extract paragraph content
+          content = if div =~ %r{<p[^>]*>(.*?)</p>}m
+                      ::Regexp.last_match(1).strip
+                    else
+                      # Fallback
+                      div.gsub(%r{<span[^>]*>.*?</span>}m, "").gsub(%r{</?div[^>]*>}, "").strip
+                    end
+
+          sections << {
+            number: section_number,
+            content: decode_html_entities(content.gsub(/<[^>]*>/, " ").gsub(/\s+/, " ").strip)
+          }
+        end
+
+        # Sort by section number
+        sections.sort_by { |section| section[:number] }
+      end
+
+      # Decode HTML entities in text
+      # @param text [String] Text with HTML entities
+      # @return [String] Text with decoded HTML entities
+      def decode_html_entities(text)
+        text.gsub(/&([a-z]+);/i) do |entity|
+          case ::Regexp.last_match(1).downcase
+          when "lt" then "<"
+          when "gt" then ">"
+          when "amp" then "&"
+          when "quot" then '"'
+          when "apos" then "'"
+          when "nbsp" then " "
+          else entity
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rospatent/railtie.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Rospatent
+  class Railtie < ::Rails::Railtie
+    # Ensure generators are loaded when Rails loads
+    generators do
+      require "generators/rospatent/install/install_generator"
+    end
+
+    # Configure Rails integration
+    config.before_configuration do
+      # Ensure generators are discoverable
+    end
+
+    # Add Rails-specific initializer
+    initializer "rospatent.configure" do
+      # Set Rails-friendly defaults
+      if defined?(::Rails.logger) && Rospatent.configuration.log_level == :debug
+        # Use Rails logger in development
+        Rospatent.configuration.instance_variable_set(:@rails_integration, true)
+      end
+    end
+  end
+end

data/lib/rospatent/search.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require_relative "input_validator"
+
+module Rospatent
+  # Search result class to handle API responses
+  class SearchResult
+    attr_reader :total, :available, :hits, :raw_response
+
+    # Initialize a search result from API response
+    # @param response [Hash] API response data
+    def initialize(response)
+      @raw_response = response
+      @total = response["total"]
+      @available = response["available"]
+      @hits = response["hits"] || []
+    end
+
+    # Check if the search has any results
+    # @return [Boolean] true if there are any hits
+    def any? = !@hits.empty?
+
+    # Return the number of hits in the current response
+    # @return [Integer] number of hits
+    def count = @hits.count
+  end
+
+  # Search class to handle search queries to the API
+  class Search
+    include InputValidator
+
+    # Initialize a new search instance
+    # @param client [Rospatent::Client] API client instance
+    def initialize(client)
+      @client = client
+    end
+
+    # Execute a search against the API
+    #
+    # @param q [String] Search query using the special query language
+    # @param qn [String] Natural language search query
+    # @param limit [Integer] Maximum number of results to return
+    # @param offset [Integer] Offset for pagination
+    # @param pre_tag [String] HTML tag to prepend to highlighted matches
+    # @param post_tag [String] HTML tag to append to highlighted matches
+    # @param sort [Symbol, String] Sort option (:relevance, :pub_date, :filing_date)
+    # @param group_by [Symbol, String] Grouping option (:patent_family)
+    # @param include_facets [Boolean] Whether to include facet information
+    # @param filter [Hash] Filters to apply to the search
+    # @param datasets [Array<String>] Datasets to search within
+    # @param highlight [Boolean] Whether to highlight matches
+    #
+    # @return [Rospatent::SearchResult] Search result object
+    def execute(
+      q: nil,
+      qn: nil,
+      limit: nil,
+      offset: nil,
+      pre_tag: nil,
+      post_tag: nil,
+      sort: nil,
+      group_by: nil,
+      include_facets: nil,
+      filter: nil,
+      datasets: nil,
+      highlight: nil
+    )
+      # Filter out nil parameters to only validate explicitly provided ones
+      params = {
+        q: q, qn: qn, limit: limit, offset: offset,
+        pre_tag: pre_tag, post_tag: post_tag, sort: sort,
+        group_by: group_by, include_facets: include_facets,
+        filter: filter, datasets: datasets, highlight: highlight
+      }.compact
+
+      # Validate and normalize parameters
+      validated_params = validate_and_normalize_params(**params)
+
+      payload = build_payload(**validated_params)
+      response = @client.post("/patsearch/v0.2/search", payload)
+      SearchResult.new(response)
+    end
+
+    private
+
+    # Validate and normalize all search parameters
+    # @param params [Hash] Search parameters
+    # @return [Hash] Validated and normalized parameters
+    # @raise [Rospatent::Errors::ValidationError] when validation fails
+    def validate_and_normalize_params(**params)
+      # Check that at least one query parameter is provided
+      unless params[:q] || params[:qn]
+        raise Errors::InvalidRequestError,
+              "Either 'q' or 'qn' parameter must be provided for search"
+      end
+
+      validated = {}
+
+      # Validate query parameters
+      validated[:q] = validate_string(params[:q], "q", max_length: 1000) if params[:q]
+      validated[:qn] = validate_string(params[:qn], "qn", max_length: 1000) if params[:qn]
+
+      # Validate pagination parameters (only if provided)
+      if params[:limit]
+        validated[:limit] =
+          validate_positive_integer(params[:limit], "limit", min_value: 1, max_value: 100)
+      end
+      if params[:offset]
+        validated[:offset] =
+          validate_positive_integer(params[:offset], "offset", min_value: 0, max_value: 10_000)
+      end
+
+      # Validate highlighting parameters (only if provided)
+      if params.key?(:highlight)
+        validated[:highlight] = !!params[:highlight]
+        if params[:highlight] && params[:pre_tag]
+          validated[:pre_tag] =
+            validate_string(params[:pre_tag], "pre_tag", max_length: 50)
+        end
+        if params[:highlight] && params[:post_tag]
+          validated[:post_tag] =
+            validate_string(params[:post_tag], "post_tag", max_length: 50)
+        end
+      end
+
+      # Validate sort parameter (only if provided)
+      validated[:sort] = validate_sort_parameter(params[:sort]) if params[:sort]
+
+      # Validate group_by parameter (only if provided)
+      if params[:group_by]
+        validated[:group_by] = validate_enum(params[:group_by], [:patent_family], "group_by")
+      end
+
+      # Validate boolean parameters (only if provided)
+      validated[:include_facets] = !params[:include_facets].nil? if params.key?(:include_facets)
+
+      # Validate filter parameter
+      validated[:filter] = validate_hash(params[:filter], "filter") if params[:filter]
+
+      # Validate datasets parameter
+      if params[:datasets]
+        validated[:datasets] = validate_array(params[:datasets], "datasets", max_size: 10) do |dataset|
+          validate_string(dataset, "dataset")
+        end
+      end
+
+      validated.compact
+    end
+
+    # Build the search payload
+    # @param params [Hash] Validated search parameters
+    # @return [Hash] Search request payload
+    def build_payload(**params)
+      payload = {}
+
+      # Add query parameters (required)
+      payload[:q] = params[:q] if params[:q]
+      payload[:qn] = params[:qn] if params[:qn]
+
+      # Add pagination parameters (only if explicitly provided)
+      payload[:limit] = params[:limit] if params[:limit]
+      payload[:offset] = params[:offset] if params[:offset]
+
+      # Add highlighting parameters (only if explicitly provided)
+      if params.key?(:highlight)
+        payload[:highlight] = params[:highlight]
+        payload[:pre_tag] = params[:pre_tag] if params[:pre_tag]
+        payload[:post_tag] = params[:post_tag] if params[:post_tag]
+      end
+
+      # Add sort parameter (only if explicitly provided)
+      payload[:sort] = params[:sort] if params[:sort]
+
+      # Add grouping parameter (only if explicitly provided)
+      payload[:group_by] = "patent_family" if params[:group_by] == :patent_family
+
+      # Add other parameters (only if explicitly provided)
+      payload[:include_facets] = params[:include_facets] if params.key?(:include_facets)
+      payload[:filter] = params[:filter] if params[:filter]
+      payload[:datasets] = params[:datasets] if params[:datasets]
+
+      payload
+    end
+
+    # Validate and normalize sort parameter according to API documentation
+    # @param sort_value [String, Symbol] Sort parameter value
+    # @return [String] Normalized sort parameter
+    # @raise [Rospatent::Errors::ValidationError] If sort parameter is invalid
+    def validate_sort_parameter(sort_value)
+      return nil unless sort_value
+
+      # Allowed values according to API documentation
+      allowed_values = [
+        "relevance",
+        "publication_date:asc",
+        "publication_date:desc",
+        "filing_date:asc",
+        "filing_date:desc"
+      ]
+
+      # Convert and normalize the sort parameter
+      normalized = case sort_value.to_s
+                   when "relevance" then "relevance"
+                   when "pub_date" then "publication_date:desc"    # Default to desc for backward compatibility
+                   when "filing_date" then "filing_date:desc"      # Default to desc for backward compatibility
+                   when "publication_date:asc", "publication_date:desc",
+                        "filing_date:asc", "filing_date:desc"
+                     sort_value.to_s
+                   else
+                     sort_value.to_s
+                   end
+
+      # Validate against allowed values
+      unless allowed_values.include?(normalized)
+        raise Errors::ValidationError,
+              "Invalid sort parameter. Allowed values: #{allowed_values.join(', ')}"
+      end
+
+      normalized
+    end
+  end
+end

data/lib/rospatent/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Rospatent
+  VERSION = "1.0.0"
+end