rospatent 1.0.0

data/lib/rospatent/configuration.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Rospatent
+  # Configuration class for Rospatent API client
+  class Configuration
+    ENVIRONMENTS = %w[development staging production].freeze
+
+    # Base URL for the Rospatent API
+    attr_accessor :api_url
+    # JWT token for authentication
+    attr_accessor :token
+    # Request timeout in seconds
+    attr_accessor :timeout
+    # Number of retries for failed requests
+    attr_accessor :retry_count
+    # User agent to be sent with requests
+    attr_accessor :user_agent
+    # Current environment
+    attr_accessor :environment
+    # Cache configuration
+    attr_accessor :cache_enabled, :cache_ttl, :cache_max_size
+    # Logging configuration
+    attr_accessor :log_level, :log_requests, :log_responses
+    # Token management
+    attr_accessor :token_expires_at, :token_refresh_callback
+    # Connection pooling
+    attr_accessor :connection_pool_size, :connection_keep_alive
+
+    # Initialize a new configuration with default values
+    def initialize
+      @api_url = "https://searchplatform.rospatent.gov.ru"
+      @token = nil
+      @timeout = 30
+      @retry_count = 3
+      @user_agent = "Rospatent Ruby Client/#{Rospatent::VERSION}"
+
+      # Environment configuration
+      @environment = ENV.fetch("ROSPATENT_ENV", "development")
+
+      # Cache configuration
+      @cache_enabled = ENV.fetch("ROSPATENT_CACHE_ENABLED", "true") == "true"
+      @cache_ttl = ENV.fetch("ROSPATENT_CACHE_TTL", "300").to_i
+      @cache_max_size = ENV.fetch("ROSPATENT_CACHE_MAX_SIZE", "1000").to_i
+
+      # Logging configuration
+      @log_level = ENV.fetch("ROSPATENT_LOG_LEVEL", "info").to_sym
+      @log_requests = ENV.fetch("ROSPATENT_LOG_REQUESTS", "false") == "true"
+      @log_responses = ENV.fetch("ROSPATENT_LOG_RESPONSES", "false") == "true"
+
+      # Token management
+      @token_expires_at = nil
+      @token_refresh_callback = nil
+
+      # Connection pooling
+      @connection_pool_size = ENV.fetch("ROSPATENT_POOL_SIZE", "5").to_i
+      @connection_keep_alive = ENV.fetch("ROSPATENT_KEEP_ALIVE", "true") == "true"
+
+      load_environment_config
+    end
+
+    # Check if the current token is still valid
+    # @return [Boolean] true if token is valid or no expiration is set
+    def token_valid?
+      return true unless @token_expires_at
+
+      Time.now < @token_expires_at
+    end
+
+    # Validate the current environment
+    # @return [Boolean] true if environment is valid
+    def valid_environment?
+      ENVIRONMENTS.include?(@environment)
+    end
+
+    # Get environment-specific API URL if needed
+    # @return [String] API URL for current environment
+    def effective_api_url
+      case @environment
+      when "development"
+        ENV.fetch("ROSPATENT_DEV_API_URL", @api_url)
+      when "staging"
+        ENV.fetch("ROSPATENT_STAGING_API_URL", @api_url)
+      when "production"
+        @api_url
+      else
+        @api_url
+      end
+    end
+
+    # Reset configuration to defaults
+    def reset!
+      initialize
+    end
+
+    # Configure from hash
+    # @param options [Hash] Configuration options
+    def configure_from_hash(options)
+      options.each do |key, value|
+        setter = "#{key}="
+        send(setter, value) if respond_to?(setter)
+      end
+    end
+
+    private
+
+    # Load environment-specific configuration
+    def load_environment_config
+      unless valid_environment?
+        raise ArgumentError, "Invalid environment: #{@environment}. " \
+                             "Allowed: #{ENVIRONMENTS.join(', ')}"
+      end
+
+      case @environment
+      when "production"
+        @timeout = 60
+        @retry_count = 5
+        @log_level = :warn
+        @cache_ttl = 600 # 10 minutes in production
+      when "staging"
+        @timeout = 45
+        @retry_count = 3
+        @log_level = :info
+        @cache_ttl = 300 # 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
+      end
+    end
+  end
+end

data/lib/rospatent/errors.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Rospatent
+  # Error classes for the Rospatent API client
+  module Errors
+    # Base error class for all Rospatent API errors
+    class Error < StandardError; end
+
+    # Raised when authentication token is missing
+    class MissingTokenError < Error; end
+
+    # Raised when authentication fails
+    class AuthenticationError < Error; end
+
+    # Raised when the API returns an error response
+    class ApiError < Error
+      attr_reader :status_code, :response_body, :request_id
+
+      # Initialize a new API error
+      # @param message [String] Error message
+      # @param status_code [Integer] HTTP status code
+      # @param response_body [String] Response body from API
+      # @param request_id [String] Request ID for tracking
+      def initialize(message, status_code = nil, response_body = nil, request_id = nil)
+        @status_code = status_code
+        @response_body = response_body
+        @request_id = request_id
+        super(message)
+      end
+
+      # Provide more descriptive error message
+      # @return [String] Formatted error message
+      def to_s
+        msg = "API Error (#{@status_code || 'unknown'}): #{super}"
+        msg += " [Request ID: #{@request_id}]" if @request_id
+        msg
+      end
+
+      # Check if error is retryable based on status code
+      # @return [Boolean] true if the error might be temporary
+      def retryable?
+        return false unless @status_code
+
+        # Retryable status codes: 408, 429, 500, 502, 503, 504
+        [408, 429, 500, 502, 503, 504].include?(@status_code)
+      end
+    end
+
+    # Raised when API rate limit is exceeded
+    class RateLimitError < ApiError
+      attr_reader :retry_after
+
+      # Initialize a new rate limit error
+      # @param message [String] Error message
+      # @param status_code [Integer] HTTP status code
+      # @param retry_after [Integer] Seconds to wait before retrying
+      def initialize(message, status_code = 429, retry_after = nil)
+        @retry_after = retry_after
+        super(message, status_code)
+      end
+
+      def to_s
+        msg = super
+        msg += " Retry after #{@retry_after} seconds." if @retry_after
+        msg
+      end
+    end
+
+    # Raised when a resource is not found
+    class NotFoundError < ApiError
+      def initialize(message = "Resource not found", status_code = 404)
+        super
+      end
+    end
+
+    # Raised for connection-related errors
+    class ConnectionError < Error
+      attr_reader :original_error
+
+      def initialize(message, original_error = nil)
+        @original_error = original_error
+        super(message)
+      end
+
+      def to_s
+        msg = super
+        msg += " (#{@original_error.class}: #{@original_error.message})" if @original_error
+        msg
+      end
+    end
+
+    # Raised when request times out
+    class TimeoutError < ConnectionError; end
+
+    # Raised for malformed request errors
+    class InvalidRequestError < Error; end
+
+    # Raised for validation errors with detailed field information
+    class ValidationError < InvalidRequestError
+      attr_reader :errors
+
+      # Initialize a new validation error
+      # @param message [String] Error message
+      # @param errors [Hash] Field-specific validation errors
+      def initialize(message, errors = {})
+        @errors = errors
+        super(message)
+      end
+
+      def to_s
+        msg = super
+        if @errors&.any?
+          field_errors = @errors.map { |field, error| "#{field}: #{error}" }
+          msg += " (#{field_errors.join(', ')})"
+        end
+        msg
+      end
+    end
+
+    # Raised when server is temporarily unavailable
+    class ServiceUnavailableError < ApiError
+      def initialize(message = "Service temporarily unavailable", status_code = 503)
+        super
+      end
+    end
+  end
+end

data/lib/rospatent/input_validator.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Rospatent
+  # Module for validating input parameters and converting types
+  module InputValidator
+    # Validate and normalize date input
+    # @param date [String, Date, nil] Date input to validate
+    # @param field_name [String] Name of the field for error messages
+    # @return [Date] Normalized Date object
+    # @raise [ValidationError] If date format is invalid
+    def validate_date(date, field_name = "date")
+      return nil if date.nil?
+      return date if date.is_a?(Date)
+
+      if date.is_a?(String)
+        begin
+          return Date.parse(date)
+        rescue Date::Error
+          raise Errors::ValidationError,
+                "Invalid #{field_name} format. Expected YYYY-MM-DD or Date object"
+        end
+      end
+
+      raise Errors::ValidationError,
+            "Invalid #{field_name} type. Expected String or Date, got #{date.class}"
+    end
+
+    # Validate and normalize required date input (does not allow nil)
+    # @param date [String, Date] Date input to validate
+    # @param field_name [String] Name of the field for error messages
+    # @return [Date] Normalized Date object
+    # @raise [ValidationError] If date format is invalid or nil
+    def validate_required_date(date, field_name = "date")
+      raise Errors::ValidationError, "#{field_name.capitalize} is required" if date.nil?
+
+      validate_date(date, field_name)
+    end
+
+    # Validate positive integer
+    # @param value [Integer, String, nil] Value to validate
+    # @param field_name [String] Name of the field for error messages
+    # @param min_value [Integer] Minimum allowed value
+    # @param max_value [Integer, nil] Maximum allowed value (optional)
+    # @return [Integer] Validated integer
+    # @raise [ValidationError] If value is invalid
+    def validate_positive_integer(value, field_name, min_value: 1, max_value: nil)
+      return nil if value.nil?
+
+      # Convert string to integer if possible
+      if value.is_a?(String)
+        begin
+          value = Integer(value)
+        rescue ArgumentError
+          raise Errors::ValidationError,
+                "Invalid #{field_name}. Expected integer, got non-numeric string"
+        end
+      end
+
+      unless value.is_a?(Integer)
+        raise Errors::ValidationError,
+              "Invalid #{field_name} type. Expected Integer, got #{value.class}"
+      end
+
+      if value < min_value
+        raise Errors::ValidationError,
+              "#{field_name.capitalize} must be at least #{min_value}"
+      end
+
+      if max_value && value > max_value
+        raise Errors::ValidationError,
+              "#{field_name.capitalize} must be at most #{max_value}"
+      end
+
+      value
+    end
+
+    # Validate non-empty string
+    # @param value [String, nil] String to validate
+    # @param field_name [String] Name of the field for error messages
+    # @param max_length [Integer, nil] Maximum allowed length
+    # @return [String] Validated string
+    # @raise [ValidationError] If string is invalid
+    def validate_string(value, field_name, max_length: nil)
+      return nil if value.nil?
+
+      unless value.is_a?(String)
+        raise Errors::ValidationError,
+              "Invalid #{field_name} type. Expected String, got #{value.class}"
+      end
+
+      raise Errors::ValidationError, "#{field_name.capitalize} cannot be empty" if value.empty?
+
+      if max_length && value.length > max_length
+        raise Errors::ValidationError,
+              "#{field_name.capitalize} cannot exceed #{max_length} characters"
+      end
+
+      value.strip
+    end
+
+    # Validate required non-empty string (does not allow nil)
+    # @param value [String, nil] String to validate
+    # @param field_name [String] Name of the field for error messages
+    # @param max_length [Integer, nil] Maximum allowed length
+    # @return [String] Validated string
+    # @raise [ValidationError] If string is invalid or nil
+    def validate_required_string(value, field_name, max_length: nil)
+      raise Errors::ValidationError, "#{field_name.capitalize} is required" if value.nil?
+
+      unless value.is_a?(String)
+        raise Errors::ValidationError,
+              "Invalid #{field_name} type. Expected String, got #{value.class}"
+      end
+
+      raise Errors::ValidationError, "#{field_name.capitalize} cannot be empty" if value.empty?
+
+      if max_length && value.length > max_length
+        raise Errors::ValidationError,
+              "#{field_name.capitalize} cannot exceed #{max_length} characters"
+      end
+
+      value.strip
+    end
+
+    # Validate enum value
+    # @param value [Symbol, String, nil] Value to validate
+    # @param allowed_values [Array] Array of allowed values
+    # @param field_name [String] Name of the field for error messages
+    # @return [Symbol] Validated symbol
+    # @raise [ValidationError] If value is not in allowed list
+    def validate_enum(value, allowed_values, field_name)
+      return nil if value.nil?
+
+      # Convert to symbol for consistency
+      value = value.to_sym if value.respond_to?(:to_sym)
+
+      # Convert allowed values to symbols for comparison
+      allowed_symbols = allowed_values.map(&:to_sym)
+
+      unless allowed_symbols.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
+    # @param max_size [Integer, nil] Maximum array size
+    # @param element_validator [Proc, nil] Proc to validate each element
+    # @return [Array] Validated array
+    # @raise [ValidationError] If array is invalid
+    def validate_array(value, field_name, max_size: nil, element_validator: nil)
+      return nil if value.nil?
+
+      unless value.is_a?(Array)
+        raise Errors::ValidationError,
+              "Invalid #{field_name} type. Expected Array, got #{value.class}"
+      end
+
+      raise Errors::ValidationError, "#{field_name.capitalize} cannot be empty" if value.empty?
+
+      if max_size && value.size > max_size
+        raise Errors::ValidationError,
+              "#{field_name.capitalize} cannot contain more than #{max_size} items"
+      end
+
+      if element_validator
+        value.each_with_index do |element, index|
+          element_validator.call(element)
+        rescue Errors::ValidationError => e
+          raise Errors::ValidationError,
+                "Invalid #{field_name}[#{index}]: #{e.message}"
+        rescue StandardError => e
+          raise Errors::ValidationError,
+                "Invalid #{field_name}[#{index}]: #{e.message}"
+        end
+      end
+
+      value
+    end
+
+    # Validate hash parameter
+    # @param value [Hash, nil] Hash to validate
+    # @param field_name [String] Name of the field for error messages
+    # @param required_keys [Array] Required keys in the hash
+    # @param allowed_keys [Array, nil] Allowed keys (if nil, any keys allowed)
+    # @return [Hash] Validated hash
+    # @raise [ValidationError] If hash is invalid
+    def validate_hash(value, field_name, required_keys: [], allowed_keys: nil)
+      return nil if value.nil?
+
+      unless value.is_a?(Hash)
+        raise Errors::ValidationError,
+              "Invalid #{field_name} type. Expected Hash, got #{value.class}"
+      end
+
+      # Check required keys
+      missing_keys = required_keys.map(&:to_s) - value.keys.map(&:to_s)
+      unless missing_keys.empty?
+        raise Errors::ValidationError,
+              "Missing required #{field_name} keys: #{missing_keys.join(', ')}"
+      end
+
+      # Check allowed keys if specified
+      if allowed_keys
+        invalid_keys = value.keys.map(&:to_s) - allowed_keys.map(&:to_s)
+        unless invalid_keys.empty?
+          raise Errors::ValidationError,
+                "Invalid #{field_name} keys: #{invalid_keys.join(', ')}"
+        end
+      end
+
+      value
+    end
+
+    # Validate patent ID format
+    # @param document_id [String] Patent document ID
+    # @return [String] Validated document ID
+    # @raise [ValidationError] If format is invalid
+    def validate_patent_id(document_id)
+      raise Errors::ValidationError, "Document_id is required" if document_id.nil?
+
+      value = validate_string(document_id, "document_id")
+      return nil if value.nil?
+
+      # Regex pattern for patent IDs
+      # Format: {country code (2 letters)}{publication number (alphanumeric)}{document type (letter+digits)}_{date (YYYYMMDD)}
+      pattern = /^[A-Z]{2}[A-Z0-9]+[A-Z]\d*_\d{8}$/
+
+      unless value.match?(pattern)
+        raise Errors::ValidationError,
+              "Invalid patent ID format. Expected format: 'XX12345Y1_YYYYMMDD' (country code + alphanumeric publication number + document type + date)"
+      end
+
+      value
+    end
+
+    # Validate multiple parameters at once
+    # @param params [Hash] Parameters to validate
+    # @param validations [Hash] Validation rules for each parameter
+    # @return [Hash] Hash of validated parameters
+    # @raise [ValidationError] If any validation fails
+    # @example
+    #   validate_params(
+    #     { limit: "10", offset: "0" },
+    #     {
+    #       limit: { type: :positive_integer, max_value: 100 },
+    #       offset: { type: :positive_integer, min_value: 0 }
+    #     }
+    #   )
+    def validate_params(params, validations)
+      validated = {}
+      errors = {}
+
+      validations.each do |param_name, rules|
+        value = params[param_name]
+        validated[param_name] = case rules[:type]
+                                when :positive_integer
+                                  validate_positive_integer(
+                                    value,
+                                    param_name.to_s,
+                                    min_value: rules[:min_value] || 1,
+                                    max_value: rules[:max_value]
+                                  )
+                                when :string
+                                  validate_string(
+                                    value,
+                                    param_name.to_s,
+                                    max_length: rules[:max_length]
+                                  )
+                                when :enum
+                                  validate_enum(value, rules[:allowed_values], param_name.to_s)
+                                when :date
+                                  validate_date(value, param_name.to_s)
+                                when :array
+                                  validate_array(
+                                    value,
+                                    param_name.to_s,
+                                    max_size: rules[:max_size],
+                                    element_validator: rules[:element_validator]
+                                  )
+                                when :hash
+                                  validate_hash(
+                                    value,
+                                    param_name.to_s,
+                                    required_keys: rules[:required_keys] || [],
+                                    allowed_keys: rules[:allowed_keys]
+                                  )
+                                else
+                                  value
+                                end
+      rescue Errors::ValidationError => e
+        errors[param_name] = e.message
+      end
+
+      raise Errors::ValidationError.new("Validation failed", errors) unless errors.empty?
+
+      validated.compact
+    end
+  end
+end