rospatent 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c95c34be848baa76a4286b680399c4b76a10b5d4e699776c9d6d735ccbcf4e07
-  data.tar.gz: fdc55a2649fbaa37d4af103929a1cd25747aae7a409512e052da187b832197ef
+  metadata.gz: f0fd09ca7a6d13e73a4ec4af7f9e06e4e4a5c640607b551c614289898d83a177
+  data.tar.gz: 76cca6feb25bf64b8c069059470f87e7aef159331f93a0fccb2e7147df69cbab
 SHA512:
-  metadata.gz: cdf8239372f22f997aaca78ec400574a6ad26e470f2827e8c465aba6e6a15958c6f3caf6efa602245d58be3f7612929da720cfb77ffe12a871bb77878b084bc1
-  data.tar.gz: d852ecfd4103fb1d4bd22b6bc64b1c22f5e63ea8329c01dabd554e8503f647b7f049680fc35ff43d5b30e5e3ca7d94e3f6daf83ea6446d3f6d20e4debe51ed54
+  metadata.gz: 1022920b2f35d2db3558c6df5668db8421df46bbdba2ee13a40d5119a36ca5e3e4a4fb33d8432a10f088fa8dfcb9d1333a7a9b05f4c1ba287ddc8887cf3f32b8
+  data.tar.gz: 8ce447fae3280ee2d0a4ff83ab481c8a47321bddcb2cbd310c557d01700635ea271079dcda98f4993d312573d3ec29404a02377743396c2b38ac2f60498d5593

data/CHANGELOG.md

@@ -5,6 +5,24 @@ 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

data/README.md

@@ -230,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")
@@ -279,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
 ```
 
@@ -617,6 +619,7 @@ The library uses **Faraday** as the HTTP client with redirect support for all en
 - **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.
 
@@ -920,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")
@@ -970,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
 ```
 
@@ -1096,6 +1102,7 @@ end
 - **Поиск похожих патентов по тексту**: Иногда возвращает `503 Service Unavailable` (проблема сервера, не клиентской реализации)
 ⚠️ **Неточности документации**:
 - **Поиск похожих патентов**: Массив совпадений в документации назван `hits`, фактическая реализация использует `data`
+- **Перечень датасетов**: Ключ `name` в фактической реализации содержит признак локализации — `name_ru`, `name_en` 
 
 Вся основная функциональность реализована и готова для продакшена.
 

data/lib/rospatent/client.rb

@@ -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)
@@ -642,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
@@ -695,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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rospatent
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Aleksandr Dryzhuk
@@ -140,8 +140,8 @@ licenses:
 metadata:
   homepage_uri: https://github.com/amdest/rospatent
   source_code_uri: https://github.com/amdest/rospatent
-  changelog_uri: https://github.com/amdest/rospatent/blob/main/CHANGELOG.md
-  documentation_uri: https://github.com/amdest/rospatent/blob/main/README.md
+  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'