rospatent 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8da1e945c9c210cef707bd01b1c603a98ce95e9a7df67428214d08653282abc
-  data.tar.gz: 487776845930d34da3198ecb52a8a1fb0e8690dae4d099409721990c20ac7f70
+  metadata.gz: f0fd09ca7a6d13e73a4ec4af7f9e06e4e4a5c640607b551c614289898d83a177
+  data.tar.gz: 76cca6feb25bf64b8c069059470f87e7aef159331f93a0fccb2e7147df69cbab
 SHA512:
-  metadata.gz: 7f5b2739d6c9c5759383e4439b8ffc3f3e17cc1384e5778dfd93b795b6da39bce8ab7887a6dd18a4294671741fccb731c0deaa475c8a04b0c42286ebcb75cee3
-  data.tar.gz: 5582c35ea773a88d4187c79ffa16d0b7cbed19d2915375b4740980fa716daff15a07c3730936562683fc8c7093e75d68d833e7dbe697ecf79ee5079b68887a23
+  metadata.gz: 1022920b2f35d2db3558c6df5668db8421df46bbdba2ee13a40d5119a36ca5e3e4a4fb33d8432a10f088fa8dfcb9d1333a7a9b05f4c1ba287ddc8887cf3f32b8
+  data.tar.gz: 8ce447fae3280ee2d0a4ff83ab481c8a47321bddcb2cbd310c557d01700635ea271079dcda98f4993d312573d3ec29404a02377743396c2b38ac2f60498d5593

data/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2025-06-04
+
+### Added
+- Binary data support for `patent_media` and `patent_media_by_id` methods to properly handle PDF, image, and other media files
+- New `binary` parameter for `get` method to distinguish between JSON and binary responses
+- New `handle_binary_response` method for processing binary API responses with proper error handling
+- Russian patent number formatting with automatic zero-padding to 10 digits
+- New `format_publication_number` private method for consistent number formatting across media methods
+
+### Fixed
+- API endpoint paths for `classification_search` and `classification_code` methods now include trailing slashes to prevent 404 errors
+- Binary data corruption issue when downloading patent media files (PDFs, images) through media endpoints
+
+### Changed
+- Enhanced test coverage for binary data handling and publication number formatting
+- Updated README documentation for classification search examples and dataset display conventions
+- Improved error handling consistency for binary vs JSON responses
+
+## [1.1.0] - 2025-06-04
+
+### Added
+- Word count validation for `similar_patents_by_text` method (minimum 50 words required)
+- New `validate_text_with_word_count` validation method with configurable minimum word requirements
+- Staging environment configuration documentation and examples
+- Enhanced Russian documentation sections
+
+### Changed
+- Improved error handling for insufficient word count with descriptive messages showing current vs required count
+- Error type changed from `InvalidRequestError` to `ValidationError` for text validation consistency
+
+### Fixed
+- Documentation clarifications for similar patents API response format (`data` vs `hits` naming)
+- Updated README examples to use correct API response structure
+- Corrected minimum word requirements documentation for text-based similarity search
+
 ## [1.0.0] - 2025-06-03
 
 ### Added

data/README.md

@@ -1,5 +1,7 @@
 # Rospatent
 
+[![Gem Version](https://badge.fury.io/rb/rospatent.svg)](https://badge.fury.io/rb/rospatent)
+
 A comprehensive Ruby client for the Rospatent patent search API with advanced features including intelligent caching, input validation, structured logging, and robust error handling.
 
 > 🇷🇺 **[Документация на русском языке](#-документация-на-русском-языке)** доступна ниже
@@ -211,13 +213,13 @@ similar = client.similar_patents_by_id("RU134694U1_20131120", count: 50)
 
 # Find similar patents by text description
 similar = client.similar_patents_by_text(
-  "Ракетный двигатель с улучшенной тягой",
+  "Ракетный двигатель с улучшенной тягой ...", # 50 words in request minimum
   count: 25
 )
 
 # Process similar patents
-similar["hits"]&.each do |patent|
-  puts "Similar: #{patent['id']} (score: #{patent['_score']})"
+similar["data"]&.each do |patent|
+  puts "Similar: #{patent['id']} (score: #{patent['similarity']} (#{patent['similarity_norm']}))"
 end
 ```
 
@@ -228,20 +230,20 @@ Search within patent classification systems (IPC and CPC) and get detailed infor
 ```ruby
 # Search for classification codes related to rockets in IPC
 ipc_results = client.classification_search("ipc", query: "ракета", lang: "ru")
-puts "Found #{ipc_results['total']} IPC codes"
+puts "Found #{ipc_results.size} IPC codes"
 
-ipc_results["hits"]&.each do |hit|
-  puts "#{hit['code']}: #{hit['description']}"
+ipc_results&.each do |result|
+  puts "#{result['Code']}: #{result['Description']}"
 end
 
 # Search for rocket-related codes in CPC using English
 cpc_results = client.classification_search("cpc", query: "rocket", lang: "en")
 
 # Get detailed information about a specific classification code
-code_info = client.classification_code("ipc", code: "F02K9/00", lang: "ru")
-puts "Code: #{code_info['code']}"
-puts "Description: #{code_info['description']}"
-puts "Hierarchy: #{code_info['hierarchy']&.join(' → ')}"
+code, info = client.classification_code("ipc", code: "F02K9/00", lang: "ru")&.first
+puts "Code: #{code}"
+puts "Description: #{info&.first['Description']}"
+puts "Hierarchy: #{info&.map{|level| level['Code']}&.join(' → ')}"
 
 # Get CPC code information in English
 cpc_info = client.classification_code("cpc", code: "B63H11/00", lang: "en")
@@ -277,9 +279,11 @@ pdf_data = client.patent_media_by_id(
 )
 
 # Get available datasets
-datasets = client.datasets_tree
-datasets.each do |dataset|
-  puts "#{dataset['id']}: #{dataset['name']}"
+datasets.each do |category|
+  puts "Category: #{category['name_en']}"
+  category.children.each do |dataset|
+    puts "  #{dataset['id']}: #{dataset['name_en']}"
+  end
 end
 ```
 
@@ -437,6 +441,20 @@ Rospatent.configure do |config|
 end
 ```
 
+### Staging Environment
+
+```ruby
+# Optimized for staging
+Rospatent.configure do |config|
+  config.environment = "staging"
+  config.token = ENV['ROSPATENT_TOKEN']
+  config.log_level = :info
+  config.cache_ttl = 300         # Longer cache for performance
+  config.timeout = 45            # Longer timeouts for reliability
+  config.retry_count = 3         # More retries for resilience
+end
+```
+
 ### Production Environment
 
 ```ruby
@@ -597,8 +615,11 @@ The library uses **Faraday** as the HTTP client with redirect support for all en
 - **All endpoints** (`/search`, `/docs/{id}`, `/similar_search`, `/datasets/tree`, etc.) - ✅ Working perfectly with Faraday
 - **Redirect handling**: Configured with `faraday-follow_redirects` middleware to handle server redirects automatically
 
-⚠️ **Minor server-side limitation**:
-- **Similar Patents by Text**: Occasionally returns `503 Service Unavailable` (server-side issue, not client implementation)
+⚠️ **Minor server-side limitations**:
+- **Similar Patents by Text**: Occasionally returns `503 Service Unavailable` (a server-side issue, not a client implementation issue)
+⚠️ **Documentation inconsistencies**:
+- **Similar Patents**: According to the documentation, the array of hits is named `hits`, but the real implementation uses the name `data`
+- **Available Datasets**: The `name` key in the real implementation has the localization suffix — `name_ru`, `name_en`
 
 All core functionality works perfectly and is production-ready with a unified HTTP approach.
 
@@ -885,13 +906,13 @@ similar = client.similar_patents_by_id("RU134694U1_20131120", count: 50)
 
 # Поиск похожих патентов по описанию текста
 similar = client.similar_patents_by_text(
-  "Ракетный двигатель с улучшенной тягой",
+  "Ракетный двигатель с улучшенной тягой ...", # минимум 50 слов в запросе
   count: 25
 )
 
 # Обработка похожих патентов
-similar["hits"]&.each do |patent|
-  puts "Похожий: #{patent['id']} (оценка: #{patent['_score']})"
+similar["data"]&.each do |patent|
+  puts "Похожий: #{patent['id']} (оценка: #{patent['similarity']} (#{patent['similarity_norm']}))"
 end
 ```
 
@@ -902,20 +923,20 @@ end
 ```ruby
 # Поиск классификационных кодов, связанных с ракетами в IPC
 ipc_results = client.classification_search("ipc", query: "ракета", lang: "ru")
-puts "Найдено #{ipc_results['total']} кодов IPC"
+puts "Найдено #{ipc_results.size} кодов IPC"
 
-ipc_results["hits"]&.each do |hit|
-  puts "#{hit['code']}: #{hit['description']}"
+ipc_results&.each do |result|
+  puts "#{result['Code']}: #{result['Description']}"
 end
 
 # Поиск кодов, связанных с ракетами в CPC на английском
 cpc_results = client.classification_search("cpc", query: "rocket", lang: "en")
 
 # Получение подробной информации о конкретном классификационном коде
-code_info = client.classification_code("ipc", code: "F02K9/00", lang: "ru")
-puts "Код: #{code_info['code']}"
-puts "Описание: #{code_info['description']}"
-puts "Иерархия: #{code_info['hierarchy']&.join(' → ')}"
+code, info = client.classification_code("ipc", code: "F02K9/00", lang: "ru")&.first
+puts "Код: #{code}"
+puts "Описание: #{info&.first['Description']}"
+puts "Иерархия: #{info&.map{|level| level['Code']}&.join(' → ')}"
 
 # Получение информации о коде CPC на английском
 cpc_info = client.classification_code("cpc", code: "B63H11/00", lang: "en")
@@ -952,8 +973,11 @@ pdf_data = client.patent_media_by_id(
 
 # Получение доступных датасетов
 datasets = client.datasets_tree
-datasets.each do |dataset|
-  puts "#{dataset['id']}: #{dataset['name']}"
+datasets.each do |category|
+  puts "Категория: #{category['name_ru']}"
+  category.children.each do |dataset|
+    puts "  #{dataset['id']}: #{dataset['name_ru']}"
+  end
 end
 ```
 
@@ -1004,25 +1028,43 @@ end
 ### Разработка
 
 ```ruby
+# Оптимизировано для разработки
 Rospatent.configure do |config|
   config.environment = "development"
   config.token = ENV['ROSPATENT_DEV_TOKEN']
   config.log_level = :debug
   config.log_requests = true
-  config.cache_ttl = 60
+  config.log_responses = true
+  config.cache_ttl = 60          # Короткий кеш для разработки
+  config.timeout = 10            # Быстрые таймауты для быстрой обратной связи
+end
+```
+
+### Staging
+
+```ruby
+# Оптимизировано для staging
+Rospatent.configure do |config|
+  config.environment = "staging"
+  config.token = ENV['ROSPATENT_TOKEN']
+  config.log_level = :info
+  config.cache_ttl = 300         # Более длительный кеш для производительности
+  config.timeout = 45            # Более длительные таймауты для надежности
+  config.retry_count = 3         # Больше повторов для устойчивости
 end
 ```
 
 ### Продакшн
 
 ```ruby
+# Оптимизировано для продакшна
 Rospatent.configure do |config|
   config.environment = "production"
   config.token = ENV['ROSPATENT_TOKEN']
   config.log_level = :warn
-  config.cache_ttl = 600
-  config.timeout = 60
-  config.retry_count = 5
+  config.cache_ttl = 600         # Более длительный кеш для производительности
+  config.timeout = 60            # Более длительные таймауты для надежности
+  config.retry_count = 5         # Больше повторов для устойчивости
 end
 ```
 
@@ -1056,8 +1098,11 @@ end
 - **Все endpoints** (`/search`, `/docs/{id}`, `/similar_search`, `/datasets/tree`, и т.д.) - ✅ Работают идеально с Faraday
 - **Обработка редиректов**: Настроена с middleware `faraday-follow_redirects` для автоматической обработки серверных редиректов
 
-⚠️ **Незначительное серверное ограничение**:
+⚠️ **Незначительные серверные ограничения**:
 - **Поиск похожих патентов по тексту**: Иногда возвращает `503 Service Unavailable` (проблема сервера, не клиентской реализации)
+⚠️ **Неточности документации**:
+- **Поиск похожих патентов**: Массив совпадений в документации назван `hits`, фактическая реализация использует `data`
+- **Перечень датасетов**: Ключ `name` в фактической реализации содержит признак локализации — `name_ru`, `name_en` 
 
 Вся основная функциональность реализована и готова для продакшена.
 

data/lib/rospatent/client.rb

@@ -147,13 +147,14 @@ module Rospatent
     end
 
     # Find patents similar to a given text
-    # @param text [String] The text to find similar patents to
+    # @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::InvalidRequestError] If text is not provided
+    # @raise [Rospatent::Errors::ValidationError] If text has insufficient words or other validation errors
     def similar_patents_by_text(text, count: 100)
-      # Validate inputs
-      validated_text = validate_string(text, "search_text", max_length: 10_000)
+      # 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,
+                                                                          max_length: 10_000)
       validated_count = validate_positive_integer(count, "count", max_value: 1000)
 
       # Check cache first (using hash of text for key)
@@ -198,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
@@ -229,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
@@ -257,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
@@ -333,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
@@ -373,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
@@ -385,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
 
@@ -394,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
 
@@ -405,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)
@@ -641,6 +657,42 @@ 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)
+        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
@@ -694,5 +746,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/input_validator.rb

@@ -100,6 +100,29 @@ module Rospatent
       value.strip
     end
 
+    # Validate text with word count requirements
+    # @param value [String, nil] Text to validate
+    # @param field_name [String] Name of the field for error messages
+    # @param min_words [Integer] Minimum required word count
+    # @param max_length [Integer, nil] Maximum allowed character length
+    # @return [String] Validated text
+    # @raise [ValidationError] If text is invalid or has insufficient words
+    def validate_text_with_word_count(value, field_name, min_words:, max_length: nil)
+      # First, apply standard string validation
+      validated_text = validate_string(value, field_name, max_length: max_length)
+      return nil if validated_text.nil?
+
+      # Count words by splitting on whitespace
+      word_count = count_words(validated_text)
+
+      if word_count < min_words
+        raise Errors::ValidationError,
+              "#{field_name.capitalize} must contain at least #{min_words} words (currently has #{word_count})"
+      end
+
+      validated_text
+    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
@@ -302,5 +325,14 @@ module Rospatent
 
       validated.compact
     end
+
+    private
+
+    # Count words in a text by splitting on whitespace
+    # @param text [String] Text to count words in
+    # @return [Integer] Number of words
+    def count_words(text)
+      text.split.size
+    end
   end
 end

data/lib/rospatent/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rospatent
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Aleksandr Dryzhuk
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-03 00:00:00.000000000 Z
+date: 2025-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -134,16 +134,16 @@ files:
 - lib/rospatent/railtie.rb
 - lib/rospatent/search.rb
 - lib/rospatent/version.rb
-homepage: https://hub.mos.ru/ad/rospatent
+homepage: https://github.com/amdest/rospatent
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://hub.mos.ru/ad/rospatent
-  source_code_uri: https://hub.mos.ru/ad/rospatent
-  changelog_uri: https://hub.mos.ru/ad/rospatent/blob/main/CHANGELOG.md
-  documentation_uri: https://hub.mos.ru/ad/rospatent/blob/main/README.md
-  bug_tracker_uri: https://hub.mos.ru/ad/rospatent/issues
-  wiki_uri: https://hub.mos.ru/ad/rospatent/wiki
+  homepage_uri: https://github.com/amdest/rospatent
+  source_code_uri: https://github.com/amdest/rospatent
+  changelog_uri: https://github.com/amdest/rospatent/blob/master/CHANGELOG.md
+  documentation_uri: https://github.com/amdest/rospatent/blob/master/README.md
+  bug_tracker_uri: https://github.com/amdest/rospatent/issues
+  wiki_uri: https://github.com/amdest/rospatent/wiki
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []