rospatent 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01cd0ab72ae339b3dab5372eebb311b6aef97fbc17f4fe8c4c00466aee363abe
-  data.tar.gz: d279cbbe0944f3f55890b62593b4480359222bae51b2c3c132baaf07d55c0347
+  metadata.gz: 415bcf677cca43f775fb9ddca9d7c11093a7f2bce4cc0298be375ffe1f1912fc
+  data.tar.gz: e7c9111a4230c5624137f380511e248e8b177dfd30fa583133c4788fc0e09917
 SHA512:
-  metadata.gz: d9f33a05a5c1b57b87baf0091300c0b46587b0567ba4def4ae1e635449a9ac7ec0d077bb630b32b2445111429ce7e86c9291daceb5ac75182bf44eb1beb5d16c
-  data.tar.gz: 950400777375b018839a8a1090db421994c36a28d0e3881b783236e50d6d5dd43ef5d0a65f9c010cd878f54aa31cb55af74b540c8240676dbcf65bc74ea39743
+  metadata.gz: c74bd899f8263fee6097bb7157d6a628f922ac4a43e36264639892b5e1d9359850b4b1cba869711a764d4ec4d55dabd81efa9432b51507bbae2c0f30c0af40e8
+  data.tar.gz: e5a9b87840af75812374e881e00184527c5c82a5d0d7589c1512c838524b958063e200366d44a70b0f1e8bf020227a3e5a72ed99abafad3bd65e0e357927422c

data/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.4.0] - 2025-06-09
+
+### Added
+- **Optional Filename Parameter**: Enhanced `patent_media` and `patent_media_by_id` methods with optional filename parameter
+  - Auto-generated filenames using formatted publication number + ".pdf" extension (e.g., "0000134694.pdf")
+  - Leverages existing `format_publication_number` logic for reliable API compatibility
+  - Provides convenient default behavior while maintaining full backward compatibility
+- **Safe Binary File Handling**: New `save_binary_file` method for proper encoding of binary data
+  - Ensures binary data (PDFs, images, etc.) is written correctly with ASCII-8BIT encoding
+  - Prevents encoding conversion errors when saving media files
+  - Includes comprehensive documentation and examples
+
+### Fixed
+- **Binary Data Encoding Issues**: Enhanced `handle_binary_response` method to properly handle binary data encoding
+  - Forces ASCII-8BIT encoding to prevent UTF-8 conversion errors
+  - Resolves `Encoding::UndefinedConversionError` when saving PDF and image files
+  - Maintains proper binary data integrity throughout the request lifecycle
+
+### Changed
+- **Enhanced Media Method Documentation**: Updated documentation with auto-generated filename examples
+  - Added examples showing both convenience (auto-filename) and explicit filename approaches
+  - Enhanced code examples in both English and Russian README sections
+  - Improved documentation structure with clear usage recommendations
+- **Comprehensive Test Coverage**: Enhanced test suite with auto-generated filename functionality
+  - Added specific tests for optional filename parameter behavior
+  - Updated existing tests to accommodate new method signatures
+  - Enhanced integration tests with fallback filename strategies
+- **README Improvements**: Updated Key Features section to remove hardcoded test counts
+  - Replaced specific numbers with qualitative descriptions of testing coverage
+  - Improved maintainability by removing numbers that become outdated quickly
+  - Enhanced focus on testing quality rather than raw metrics
+
+## [1.3.2] - 2025-06-07
+
+### Added
+- Notes about logger `formatter` parameter behavior when using `Rails.logger` as `output`
+
 ## [1.3.1] - 2025-06-06
 
 ### Fixed

data/README.md

@@ -15,7 +15,7 @@ A comprehensive Ruby client for the Rospatent patent search API with advanced fe
 - 📊 **Structured Logging** - JSON/text logging with request/response tracking
 - 🚀 **Batch Operations** - Process multiple patents concurrently
 - ⚙️ **Environment-Aware** - Different configurations for dev/staging/production
-- 🧪 **Comprehensive Testing** - 232 tests with 483 assertions, comprehensive integration testing
+- 🧪 **Comprehensive Testing** - Extensive unit and integration test coverage with robust error handling validation
 - 📚 **Excellent Documentation** - Detailed examples and API documentation
 
 ## Installation
@@ -583,23 +583,48 @@ end
 ### Media and Documents
 
 ```ruby
-# Download patent PDF
+# ✅ Recommended: Download patent PDF with auto-generated filename
+# Automatically uses the formatted publication number (e.g., "0000134694.pdf")
+pdf_data = client.patent_media(
+  "National",       # collection_id
+  "RU",             # country_code
+  "U1",             # doc_type
+  "2013/11/20",     # pub_date
+  "134694"          # pub_number (filename auto-generated)
+)
+client.save_binary_file(pdf_data, "patent.pdf")
+
+# ✅ Alternative: Download with explicit filename
 pdf_data = client.patent_media(
   "National",       # collection_id
   "RU",             # country_code
   "U1",             # doc_type
   "2013/11/20",     # pub_date
   "134694",         # pub_number
-  "document.pdf"    # filename
+  "document.pdf"    # explicit filename
 )
-File.write("patent.pdf", pdf_data)
+client.save_binary_file(pdf_data, "patent_explicit.pdf")
 
-# Simplified method using patent ID
+# ✅ Simplified method using patent ID (auto-generated filename)
 pdf_data = client.patent_media_by_id(
   "RU134694U1_20131120",
-  "National",
-  "document.pdf"
+  "National"  # filename auto-generated as "0000134694.pdf"
+)
+client.save_binary_file(pdf_data, "patent_by_id.pdf")
+
+# ✅ Or with explicit filename for specific files
+image_data = client.patent_media_by_id(
+  "RU134694U1_20131120", 
+  "National", 
+  "image.png"  # explicit filename for non-PDF files
 )
+client.save_binary_file(image_data, "patent_image.png")
+
+# ✅ Safe file saving options:
+File.binwrite("patent.pdf", pdf_data)  # Manual binary write
+
+# ❌ Avoid: File.write can cause encoding errors with binary data
+# File.write("patent.pdf", pdf_data)  # This may fail!
 ```
 
 ## Advanced Features
@@ -676,6 +701,10 @@ client = Rospatent.client(logger: logger)
 shared_logger = Rospatent.shared_logger(level: :debug)
 ```
 
+**Notes**:
+- When using `Rails.logger`, formatting is controlled by Rails configuration, `formatter` parameter ignored
+- When using IO objects, `formatter` parameter controls output format
+
 ### Error Handling
 
 Comprehensive error handling with specific error types and improved error message extraction:
@@ -1101,7 +1130,7 @@ $ bundle exec rake release
 - 📊 **Структурированное логирование** - JSON/текстовое логирование с отслеживанием запросов/ответов
 - 🚀 **Пакетные операции** - параллельная обработка множества патентов
 - ⚙️ **Адаптивные окружения** - различные конфигурации для development/staging/production
-- 🧪 **Комплексное тестирование** - 232 теста с 483 проверками, комплексное интеграционное тестирование
+- 🧪 **Комплексное тестирование** - Обширное покрытие модульными и интеграционными тестами с валидацией обработки ошибок
 - 📚 **Отличная документация** - подробные примеры и документация API
 
 ## Установка
@@ -1665,23 +1694,48 @@ end
 ### Медиафайлы и документы
 
 ```ruby
-# Скачивание PDF патента
+# ✅ Рекомендуется: Скачивание PDF патента с автоматически генерируемым именем файла
+# Автоматически использует отформатированный номер публикации (например, "0000134694.pdf")
+pdf_data = client.patent_media(
+  "National",       # collection_id
+  "RU",             # country_code
+  "U1",             # doc_type
+  "2013/11/20",     # pub_date
+  "134694"          # pub_number (имя файла генерируется автоматически)
+)
+client.save_binary_file(pdf_data, "patent.pdf")
+
+# ✅ Альтернатива: Скачивание с явным указанием имени файла
 pdf_data = client.patent_media(
   "National",       # collection_id
   "RU",             # country_code
   "U1",             # doc_type
   "2013/11/20",     # pub_date
   "134694",         # pub_number
-  "document.pdf"    # filename
+  "document.pdf"    # явное имя файла
 )
-File.write("patent.pdf", pdf_data)
+client.save_binary_file(pdf_data, "patent_explicit.pdf")
 
-# Упрощенный метод с использованием ID патента
+# ✅ Упрощенный метод с использованием ID патента (автогенерируемое имя)
 pdf_data = client.patent_media_by_id(
   "RU134694U1_20131120",
-  "National",
-  "document.pdf"
+  "National"  # имя файла автоматически генерируется как "0000134694.pdf"
+)
+client.save_binary_file(pdf_data, "patent_by_id.pdf")
+
+# ✅ Или с явным именем файла для конкретных файлов
+image_data = client.patent_media_by_id(
+  "RU134694U1_20131120", 
+  "National", 
+  "image.png"  # явное имя файла для файлов не-PDF
 )
+client.save_binary_file(image_data, "patent_image.png")
+
+# ✅ Варианты безопасного сохранения файлов:
+File.binwrite("patent.pdf", pdf_data)  # Ручная бинарная запись
+
+# ❌ Избегайте: File.write может вызвать ошибки кодировки с бинарными данными
+# File.write("patent.pdf", pdf_data)  # Это может не сработать!
 ```
 
 ## Расширенные возможности
@@ -1758,6 +1812,10 @@ client = Rospatent.client(logger: logger)
 shared_logger = Rospatent.shared_logger(level: :debug)
 ```
 
+**Комментарии**:
+- При использовании `Rails.logger`, форматирование контролируется конфигурацией Rails, параметр `formatter` игнорируется
+- При использовании IO объекта, формат определяется параметром `formatter`
+
 ### Обработка ошибок
 
 Комплексная обработка ошибок с конкретными типами ошибок и улучшенным извлечением сообщений об ошибках:

data/lib/rospatent/client.rb

@@ -214,18 +214,23 @@ module Rospatent
     # @param doc_type [String] Document type code (e.g., "U1")
     # @param pub_date [String, Date] Publication date in format YYYY/MM/DD
     # @param pub_number [String] Publication number
-    # @param filename [String] Media file name (e.g., "document.pdf")
-    # @return [String] Binary content of the requested file
+    # @param filename [String, nil] Media file name (optional, defaults to "<formatted_number>.pdf")
+    # @return [String] Binary content with ASCII-8BIT encoding
     # @raise [Rospatent::Errors::InvalidRequestError] If any required parameter is missing
+    # @example Retrieve and save a PDF with auto-generated filename
+    #   pdf_data = client.patent_media("National", "RU", "U1", "2013/11/20", "134694")
+    #   client.save_binary_file(pdf_data, "patent.pdf")
+    # @example Retrieve and save a specific file
+    #   pdf_data = client.patent_media("National", "RU", "U1", "2013/11/20", "134694", "document.pdf")
+    #   client.save_binary_file(pdf_data, "patent.pdf")
     def patent_media(collection_id, country_code, doc_type, pub_date, pub_number,
-                     filename)
+                     filename = nil)
       # Validate and normalize inputs
       validated_collection = validate_required_string(collection_id, "collection_id")
       validated_country = validate_required_string(country_code, "country_code", max_length: 2)
       validated_doc_type = validate_required_string(doc_type, "doc_type", max_length: 3)
       validated_date = validate_required_date(pub_date, "pub_date")
       validated_number = validate_required_string(pub_number, "pub_number")
-      validated_filename = validate_required_string(filename, "filename")
 
       # Format publication date
       formatted_date = validated_date.strftime("%Y/%m/%d")
@@ -233,6 +238,13 @@ module Rospatent
       # Format publication number with appropriate padding
       formatted_number = format_publication_number(validated_number, validated_country)
 
+      # Generate default filename if not provided
+      validated_filename = if filename.nil?
+                             "#{formatted_number}.pdf"
+                           else
+                             validate_required_string(filename, "filename")
+                           end
+
       # Construct the path
       path = "/media/#{validated_collection}/#{validated_country}/" \
              "#{validated_doc_type}/#{formatted_date}/#{formatted_number}/" \
@@ -245,15 +257,23 @@ module Rospatent
     # 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
+    # @param filename [String, nil] Filename to retrieve (optional, defaults to "<formatted_number>.pdf")
+    # @return [String] Binary content with ASCII-8BIT encoding
     # @raise [Rospatent::Errors::InvalidRequestError] If document_id format is invalid
     #   or parameters are missing
-    def patent_media_by_id(document_id, collection_id, filename)
+    # @example Retrieve and save a PDF with auto-generated filename
+    #   pdf_data = client.patent_media_by_id("RU134694U1_20131120", "National")
+    #   client.save_binary_file(pdf_data, "patent.pdf")
+    # @example Retrieve and save a specific file
+    #   pdf_data = client.patent_media_by_id("RU134694U1_20131120", "National", "document.pdf")
+    #   client.save_binary_file(pdf_data, "patent.pdf")
+    def patent_media_by_id(document_id, collection_id, filename = nil)
       # Validate inputs
       validated_id = validate_patent_id(document_id)
       validated_collection = validate_required_string(collection_id, "collection_id")
-      validated_filename = validate_required_string(filename, "filename")
+
+      # Validate filename if provided
+      validated_filename = filename ? validate_required_string(filename, "filename") : nil
 
       # Parse the patent ID to extract components
       id_parts = parse_patent_id(validated_id)
@@ -261,12 +281,10 @@ 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
+      # If no filename provided, patent_media will generate default using format_publication_number
       patent_media(validated_collection, id_parts[:country_code], id_parts[:doc_type],
-                   formatted_date, formatted_number, validated_filename)
+                   formatted_date, id_parts[:number], validated_filename)
     end
 
     # Extract and parse the abstract content from a patent document
@@ -496,6 +514,29 @@ module Rospatent
       }
     end
 
+    # Save binary data to a file with proper encoding handling
+    # This method ensures that binary data (PDFs, images, etc.) is written correctly
+    # @param binary_data [String] Binary data returned from patent_media methods
+    # @param file_path [String] Path where to save the file
+    # @return [Integer] Number of bytes written
+    # @raise [SystemCallError] If file cannot be written
+    # @example Save a PDF file with auto-generated filename
+    #   pdf_data = client.patent_media_by_id("RU134694U1_20131120", "National")
+    #   client.save_binary_file(pdf_data, "patent.pdf")
+    # @example Save a specific file
+    #   pdf_data = client.patent_media_by_id("RU134694U1_20131120", "National", "document.pdf")
+    #   client.save_binary_file(pdf_data, "patent.pdf")
+    def save_binary_file(binary_data, file_path)
+      validate_required_string(binary_data, "binary_data")
+      validate_required_string(file_path, "file_path")
+
+      # Ensure data is properly encoded as binary
+      data_to_write = binary_data.dup.force_encoding(Encoding::ASCII_8BIT)
+
+      # Write in binary mode to prevent any encoding conversions
+      File.binwrite(file_path, data_to_write)
+    end
+
     private
 
     # Validate search parameters
@@ -662,10 +703,15 @@ module Rospatent
     # 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
+    # @return [String] Binary response data with proper encoding
     # @raise [Rospatent::Errors::ApiError] If the response is not successful
     def handle_binary_response(response, request_id = nil)
-      return response.body if response.success?
+      if response.success?
+        # Ensure binary data is properly encoded as ASCII-8BIT to prevent encoding issues
+        binary_data = response.body.dup
+        binary_data.force_encoding(Encoding::ASCII_8BIT)
+        return binary_data
+      end
 
       # For binary endpoints, error responses might still be JSON
       error_msg = begin

data/lib/rospatent/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rospatent
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors:
 - Aleksandr Dryzhuk
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-06 00:00:00.000000000 Z
+date: 2025-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday