deepl-rb 3.9.0 → 3.10.0

data/lib/deepl/requests/translation_memory/storage_base.rb

@@ -9,8 +9,11 @@ module DeepL
       ##
       # Common behaviour of the requests to a pre-signed storage URL handed out by the API, such
       # as a translation memory upload or download URL. Those URLs point outside of the DeepL
-      # API, so they are requested over their own connection and the DeepL `Authorization` header
-      # is deliberately not sent.
+      # API, so they are requested over their own connection and send only the User-Agent: neither
+      # the DeepL `Authorization` header nor other caller headers. That connection uses the same
+      # proxy, SSL and timeout options as the API connection. A non-2xx response raises the API
+      # error class for its status (e.g. DeepL::Exceptions::AuthorizationFailed for 401/403) in the
+      # module-level API and a plain DeepL::Exceptions::Error in DeepL::Client.
 
       class StorageBase < DeepL::Requests::Base
         attr_reader :storage_url
@@ -27,19 +30,48 @@ module DeepL
         private
 
         def http_client
-          @http_client ||= begin
-            client = Net::HTTP.new(uri.host, uri.port)
-            client.use_ssl = uri.scheme == 'https'
-            client
-          end
+          @http_client ||= if api.http_client_options
+                             Utils::HTTPClientBuilder.build(storage_url, api.http_client_options)
+                           else
+                             default_http_client
+                           end
+        end
+
+        def http_client_options_of(_client)
+          api.http_client_options
+        end
+
+        def default_http_client
+          client = Net::HTTP.new(uri.host, uri.port)
+          client.use_ssl = uri.scheme == 'https'
+          Utils::HTTPClientBuilder.disable_lenient_defaults(client)
         end
 
         def uri
           @uri ||= URI(storage_url)
         end
 
+        # Storage responses are not DeepL API responses, so their statuses carry none of the API's
+        # meanings: an expired URL replies 403, which is no authorization failure. DeepL::Client
+        # raises a plain error; until the next major version, the module-level API raises the API
+        # error classes it has released.
+        def validate_response!(response, request = nil)
+          return if response.is_a?(Net::HTTPSuccess)
+          raise Utils::ExceptionBuilder.new(response, request).build unless api.client?
+
+          status = response.code.to_i
+          raise Exceptions::Error.new(
+            "Request to the storage URL failed with HTTP status #{status}",
+            http_status_code: status, should_retry: status == 429 || (500..599).cover?(status)
+          )
+        end
+
+        # Only the User-Agent: the caller's from the configured +headers+, else the library's.
         def headers
-          { 'User-Agent' => api.configuration.user_agent }.merge(@additional_headers)
+          caller_agent = (api.configuration.headers || {}).find do |name, _|
+            name.to_s.casecmp?('user-agent')
+          end
+          { 'User-Agent' => caller_agent ? caller_agent.last : api.configuration.user_agent }
         end
       end
     end

data/lib/deepl/requests/translation_memory/upload_file.rb

@@ -22,7 +22,7 @@ module DeepL
         end
 
         def details
-          "HTTP Headers: #{headers}\nPayload #{file_content.bytesize} byte(s)"
+          "HTTP Headers: #{loggable_headers}\nPayload #{file_content.bytesize} byte(s)"
         end
 
         def to_s

data/lib/deepl/requests/usage.rb

@@ -22,7 +22,34 @@ module DeepL
 
       def build_usage(request, response)
         data = JSON.parse(response.body)
-        Resources::Usage.new(data['character_count'], data['character_limit'], request, response)
+        Resources::Usage.new(data['character_count'], data['character_limit'], request, response,
+                             **usage_fields(data))
+      end
+
+      def usage_fields(data)
+        details = Resources::Usage::DETAIL_TYPES.to_h { |type| [type, detail(data, type)] }
+        details.merge(products: products(data['products']),
+                      start_time: optional_time(data['start_time']),
+                      end_time: optional_time(data['end_time']))
+      end
+
+      def detail(data, type)
+        count = data["#{type}_count"]
+        limit = data["#{type}_limit"]
+        Resources::Usage::Detail.new(count, limit) unless count.nil? || limit.nil?
+      end
+
+      def products(entries)
+        return nil unless entries.is_a?(Array)
+
+        entries.grep(Hash).map { |product| Resources::UsageProduct.new(product) }
+      end
+
+      # An unexpected billing-period format must not fail the whole usage response.
+      def optional_time(value)
+        Utils::TimeParser.parse_optional_time(value) if value.is_a?(String)
+      rescue ArgumentError
+        nil
       end
 
       def path

data/lib/deepl/requests/write_improvements.rb

@@ -0,0 +1,35 @@
+# Copyright 2026 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Requests
+    # @api private
+    # Builds the results of the write endpoints (rephrase, correct) from their response.
+    module WriteImprovements
+      private
+
+      # Returns one DeepL::Resources::Text per improvement. Raises DeepL::Exceptions::Error if
+      # the response has fewer improvements than +input_count+ input texts.
+      def build_improvements(input_count, request, response)
+        improvements = JSON.parse(response.body)['improvements']
+        validate_improvement_count!(improvements, input_count)
+        improvements.map do |improvement|
+          target_language = improvement['target_language']
+          Resources::Text.new(improvement['text'], improvement['detected_source_language'], nil,
+                              request, response, nil, nil,
+                              target_language.is_a?(String) ? target_language : nil)
+        end
+      end
+
+      def validate_improvement_count!(improvements, input_count)
+        return if improvements.is_a?(Array) && improvements.size >= input_count
+
+        count = improvements.is_a?(Array) ? improvements.size : 'no'
+        raise Exceptions::Error, 'Unexpected response from the DeepL API: expected ' \
+                                 "#{input_count} improvements, got #{count}"
+      end
+    end
+  end
+end

data/lib/deepl/resources/admin_usage_report.rb

@@ -0,0 +1,73 @@
+# Copyright 2026 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Resources
+    ##
+    # Usage breakdown of an admin usage report. +speech_to_speech_minutes+ is +nil+ when the
+    # response does not contain it.
+    class AdminUsageBreakdown
+      attr_reader :total_characters, :text_translation_characters,
+                  :document_translation_characters, :text_improvement_characters,
+                  :speech_to_text_minutes, :speech_to_speech_minutes
+
+      def initialize(usage)
+        usage = {} unless usage.is_a?(Hash)
+        @total_characters = Utils::NumberParser.count(usage['total_characters'])
+        @text_translation_characters = Utils::NumberParser.count(usage['text_translation_characters'])
+        @document_translation_characters =
+          Utils::NumberParser.count(usage['document_translation_characters'])
+        @text_improvement_characters = Utils::NumberParser.count(usage['text_improvement_characters'])
+        @speech_to_text_minutes = Utils::NumberParser.minutes(usage['speech_to_text_minutes'])
+        @speech_to_speech_minutes =
+          Utils::NumberParser.optional_minutes(usage['speech_to_speech_minutes'])
+      end
+    end
+
+    ##
+    # Usage of a single API key. +usage_date+ is only set when grouped by key and day;
+    # +api_key_label+ is +nil+ when the response does not contain it.
+    class KeyUsage
+      attr_reader :api_key, :api_key_label, :usage, :usage_date
+
+      def initialize(key_usage)
+        @api_key = key_usage['api_key'].is_a?(String) ? key_usage['api_key'] : ''
+        @api_key_label = key_usage['api_key_label'].is_a?(String) ? key_usage['api_key_label'] : nil
+        @usage = AdminUsageBreakdown.new(key_usage['usage'])
+        @usage_date = Utils::TimeParser.parse_optional_utc_time(key_usage['usage_date'])
+      end
+    end
+
+    ##
+    # Admin usage analytics report. +key_usages+ is only filled when grouped by key and
+    # +key_and_day_usages+ only when grouped by key and day; otherwise they are empty.
+    # +total_usage+, +start_date+ and +end_date+ are +nil+ when the response does not contain them.
+    class AdminUsageReport < Base
+      attr_reader :total_usage, :start_date, :end_date, :group_by, :key_usages,
+                  :key_and_day_usages
+
+      def initialize(data, *args) # rubocop:disable Metrics/AbcSize
+        super(*args)
+        report = data.is_a?(Hash) ? data['usage_report'] : nil
+        report = {} unless report.is_a?(Hash)
+        total_usage = report['total_usage']
+        @total_usage = total_usage.is_a?(Hash) ? AdminUsageBreakdown.new(total_usage) : nil
+        @start_date = Utils::TimeParser.parse_optional_utc_time(report['start_date'])
+        @end_date = Utils::TimeParser.parse_optional_utc_time(report['end_date'])
+        @group_by = report['group_by'].is_a?(String) ? report['group_by'] : nil
+        @key_usages = parse_key_usages(report['key_usages'])
+        @key_and_day_usages = parse_key_usages(report['key_and_day_usages'])
+      end
+
+      private
+
+      def parse_key_usages(key_usages)
+        return [] unless key_usages.is_a?(Array)
+
+        key_usages.grep(Hash).map { |usage| KeyUsage.new(usage) }
+      end
+    end
+  end
+end

data/lib/deepl/resources/custom_tag_usage_report.rb

@@ -0,0 +1,59 @@
+# Copyright 2026 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Resources
+    ##
+    # Usage breakdown of a custom tag. +speech_to_speech_minutes+ is +nil+ when the response
+    # does not contain it.
+    class CustomTagUsageBreakdown
+      attr_reader :total_characters, :text_translation_characters,
+                  :text_improvement_characters, :speech_to_text_minutes,
+                  :speech_to_speech_minutes
+
+      def initialize(breakdown)
+        breakdown = {} unless breakdown.is_a?(Hash)
+        @total_characters = Utils::NumberParser.count(breakdown['total_characters'])
+        @text_translation_characters =
+          Utils::NumberParser.count(breakdown['text_translation_characters'])
+        @text_improvement_characters =
+          Utils::NumberParser.count(breakdown['text_improvement_characters'])
+        @speech_to_text_minutes = Utils::NumberParser.minutes(breakdown['speech_to_text_minutes'])
+        @speech_to_speech_minutes =
+          Utils::NumberParser.optional_minutes(breakdown['speech_to_speech_minutes'])
+      end
+    end
+
+    ##
+    # Usage of a single custom tag. +usage_date+ is only set when aggregated by day.
+    class CustomTagUsage
+      attr_reader :custom_tag, :breakdown, :usage_date
+
+      def initialize(usage)
+        @custom_tag = usage['custom_tag'].is_a?(String) ? usage['custom_tag'] : ''
+        @breakdown = CustomTagUsageBreakdown.new(usage['breakdown'])
+        @usage_date = Utils::TimeParser.parse_optional_utc_time(usage['usage_date'])
+      end
+    end
+
+    ##
+    # Custom tag usage analytics report. +next_page+ is +nil+ on the last page.
+    class CustomTagUsageReport < Base
+      attr_reader :aggregate_by, :start_date, :end_date, :next_page, :usage
+
+      def initialize(data, *args) # rubocop:disable Metrics/AbcSize
+        super(*args)
+        report = data.is_a?(Hash) ? data['custom_tag_usage_report'] : nil
+        report = {} unless report.is_a?(Hash)
+        @aggregate_by = report['aggregate_by'].is_a?(String) ? report['aggregate_by'] : nil
+        @start_date = Utils::TimeParser.parse_optional_utc_time(report['start_date'])
+        @end_date = Utils::TimeParser.parse_optional_utc_time(report['end_date'])
+        @next_page = report['next_page'].is_a?(Integer) ? report['next_page'] : nil
+        usages = report['usage'].is_a?(Array) ? report['usage'] : []
+        @usage = usages.grep(Hash).map { |item| CustomTagUsage.new(item) }
+      end
+    end
+  end
+end

data/lib/deepl/resources/developer_key.rb

@@ -0,0 +1,57 @@
+# Copyright 2026 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Resources
+    ##
+    # Usage limits of a developer key. A +nil+ limit means unlimited.
+    class DeveloperKeyUsageLimits
+      attr_reader :characters, :speech_to_text_milliseconds, :speech_to_speech_milliseconds
+
+      def initialize(usage_limits)
+        usage_limits = {} unless usage_limits.is_a?(Hash)
+        @characters = Utils::NumberParser.optional_count(usage_limits['characters'])
+        @speech_to_text_milliseconds =
+          Utils::NumberParser.optional_count(usage_limits['speech_to_text_milliseconds'])
+        @speech_to_speech_milliseconds =
+          Utils::NumberParser.optional_count(usage_limits['speech_to_speech_milliseconds'])
+      end
+    end
+
+    ##
+    # A developer key. +label+ and +usage_limits+ are +nil+ when the response does not contain
+    # them.
+    class DeveloperKey < Base
+      attr_reader :key_id, :label, :creation_time, :deactivated_time, :is_deactivated,
+                  :usage_limits
+
+      def initialize(developer_key, *args)
+        super(*args)
+        developer_key = {} unless developer_key.is_a?(Hash)
+        @key_id = developer_key['key_id'].is_a?(String) ? developer_key['key_id'] : ''
+        @label = developer_key['label'].is_a?(String) ? developer_key['label'] : nil
+        @creation_time = Utils::TimeParser.parse_optional_utc_time(developer_key['creation_time'])
+        @deactivated_time =
+          Utils::TimeParser.parse_optional_utc_time(developer_key['deactivated_time'])
+        @is_deactivated = developer_key['is_deactivated'] == true
+        @usage_limits = parse_usage_limits(developer_key['usage_limits'])
+      end
+
+      def deactivated?
+        is_deactivated
+      end
+
+      def to_s
+        label.nil? ? key_id : "#{label} (#{key_id})"
+      end
+
+      private
+
+      def parse_usage_limits(usage_limits)
+        usage_limits.is_a?(Hash) ? DeveloperKeyUsageLimits.new(usage_limits) : nil
+      end
+    end
+  end
+end

data/lib/deepl/resources/document_handle.rb

@@ -8,49 +8,48 @@ module DeepL
     class DocumentHandle < Base
       attr_reader :document_id, :document_key
 
-      def initialize(document_id, document_key, *args)
-        super(*args)
+      # +api+ is the connection the handle was created with; status queries go through it.
+      # A handle for a stored ID and key needs only those two: +DocumentHandle.new(id, key)+.
+      def initialize(document_id, document_key, request = nil, response = nil, api: nil)
+        super(request, response)
 
         @document_id = document_id
         @document_key = document_key
+        @api = api
       end
 
       def to_s
         "DocumentHandle: ID: #{document_id} - Key: #{document_key}"
       end
 
+      # Leaves out the connection, which holds the auth key.
+      def inspect
+        "#<#{self.class.name} document_id=#{document_id.inspect}>"
+      end
+
       ##
-      # For this DocumentHandle, waits until the document translation is finished and returns the
-      # final status of the document.
+      # For this DocumentHandle, waits until the document translation is finished (done or
+      # failed) and returns the final status of the document. Stops early only if the
+      # deprecated +max_doc_status_queries+ is configured.
       #
+      # @deprecated Use DeepL::Client#translate_document_wait_until_done instead.
       # @return [DeepL::Resources::DocumentTranslationStatus] Final status of the document
       #                                                       translation.
-
       def wait_until_document_translation_finished
-        doc_status = nil
-        max_tries = max_doc_status_queries
-        num_tries = 0
-        loop do
-          num_tries += 1
-          sleep(calculate_waiting_time(doc_status)) unless doc_status.nil?
-          doc_status = DeepL.document.get_status(self)
-          break if doc_status.finished? || num_tries > max_tries
-        end
-        doc_status
+        Deprecation.warn_once('DocumentHandle#wait_until_document_translation_finished',
+                              '[DEPRECATION] DeepL::Resources::DocumentHandle#' \
+                              'wait_until_document_translation_finished is deprecated, use ' \
+                              'DeepL::Client#translate_document_wait_until_done instead.')
+        Utils::DocumentPoller.wait_until_finished(
+          api, self, max_queries: api.configuration.max_doc_status_queries
+        )
       end
 
       private
 
-      def calculate_waiting_time(_resp)
-        # ignore _resp.seconds_remaining for now, while it is unreliable
-        5
-      end
-
-      def max_doc_status_queries
-        configured_value = DeepL.configuration.max_doc_status_queries
-        return configured_value unless configured_value.nil?
-
-        10
+      # Handles created without a connection fall back to the deprecated module configuration.
+      def api
+        @api || DeepL.send(:module_api)
       end
     end
   end

data/lib/deepl/resources/document_translation_status.rb

@@ -23,13 +23,24 @@ module DeepL
           "- Error message: #{error_message}"
       end
 
+      ##
+      # Checks if the translation is done, so the document can be downloaded.
+      #
+      # @return [Boolean] +true+ if the status is +done+.
+      def done?
+        status == Constants::DocumentStatusCode::DONE
+      end
+
       ##
       # Checks if the translation finished successfully
       #
+      # @deprecated Use #done? instead.
       # @return [true] if so
-
       def successful?
-        status == 'done'
+        Deprecation.warn_once('DeepL::Resources::DocumentTranslationStatus#successful?',
+                              '[DEPRECATION] DeepL::Resources::DocumentTranslationStatus#' \
+                              'successful? is deprecated, use #done? instead.')
+        done?
       end
 
       ##
@@ -38,7 +49,15 @@ module DeepL
       # @return [true] if so
 
       def error?
-        status == 'error'
+        status == Constants::DocumentStatusCode::ERROR
+      end
+
+      ##
+      # Checks that the translation has not failed. Also true while it is queued or translating.
+      #
+      # @return [Boolean] +true+ unless the status is +error+.
+      def ok?
+        !error?
       end
 
       ##
@@ -47,7 +66,7 @@ module DeepL
       #
       # @return [true] if so
       def finished?
-        successful? || error?
+        done? || error?
       end
     end
   end

data/lib/deepl/resources/language.rb

@@ -8,20 +8,28 @@ module DeepL
     class Language < Base
       attr_reader :code, :name
 
-      def initialize(code, name, supports_formality, *args)
+      # +client:+ is true for a language returned by DeepL::Client. @api private
+      def initialize(code, name, supports_formality, *args, client: false)
         super(*args)
 
         @code = code
         @name = name
         @supports_formality = supports_formality
+        @client = client
       end
 
       def to_s
         "#{code} - #{name}"
       end
 
+      # Whether the target language supports the +formality+ option.
+      #
+      # @return [Boolean, nil] +true+ or +false+ for a target language; for a source language
+      #   +nil+ if it came from DeepL::Client.
+      # @raise [DeepL::Exceptions::NotSupported] For a source language from the module-level
+      #   +DeepL.languages+, until the next major version.
       def supports_formality?
-        return @supports_formality unless @supports_formality.nil?
+        return @supports_formality unless @supports_formality.nil? && !@client
 
         raise Exceptions::NotSupported, 'Support formality is only available on target languages'
       end

data/lib/deepl/resources/language_resource.rb

@@ -0,0 +1,57 @@
+# Copyright 2026 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE file.
+# frozen_string_literal: true
+
+module DeepL
+  module Resources
+    # A feature supported by a DeepL API resource, as returned by `DeepL::Client#get_language_resources`.
+    class ResourceFeature
+      attr_reader :name
+
+      def initialize(feature)
+        @name = feature['name']
+        @needs_source_support = feature['needs_source_support'] ? true : false
+        @needs_target_support = feature['needs_target_support'] ? true : false
+      end
+
+      def to_s
+        name
+      end
+
+      # True if the source language must support this feature for it to be available.
+      def needs_source_support?
+        @needs_source_support
+      end
+
+      # True if the target language must support this feature for it to be available.
+      def needs_target_support?
+        @needs_target_support
+      end
+    end
+
+    # A DeepL API resource and the features it supports, as returned by `DeepL::Client#get_language_resources`.
+    class LanguageResource < Base
+      attr_reader :name, :features
+
+      def initialize(resource, *args)
+        super(*args)
+
+        @name = resource['name']
+        @features = (resource['features'] || []).to_h do |feature|
+          resource_feature = ResourceFeature.new(feature)
+          [resource_feature.name, resource_feature]
+        end
+      end
+
+      def to_s
+        name
+      end
+
+      # Returns true if this resource exposes the given feature (e.g. 'glossary').
+      def supports?(feature)
+        features.key?(feature.to_s)
+      end
+    end
+  end
+end

data/lib/deepl/resources/language_support.rb

@@ -0,0 +1,56 @@
+# Copyright 2026 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE file.
+# frozen_string_literal: true
+
+module DeepL
+  module Resources
+    # Support level of a single feature of a language for a resource.
+    class LanguageFeature
+      attr_reader :status
+
+      def initialize(status)
+        @status = status
+      end
+
+      def to_s
+        status.to_s
+      end
+    end
+
+    # A language supported by a DeepL API resource, as returned by `DeepL::Client#get_languages_for_resource`.
+    class LanguageSupport < Base
+      attr_reader :code, :name, :status, :features
+
+      def initialize(language, *args)
+        super(*args)
+
+        @code = language['lang']
+        @name = language['name']
+        @status = language['status']
+        @usable_as_source = language['usable_as_source'] ? true : false
+        @usable_as_target = language['usable_as_target'] ? true : false
+        @features = (language['features'] || {}).to_h.transform_values do |feature|
+          LanguageFeature.new(feature.to_h['status'])
+        end
+      end
+
+      def to_s
+        "#{name} (#{code})"
+      end
+
+      def usable_as_source?
+        @usable_as_source
+      end
+
+      def usable_as_target?
+        @usable_as_target
+      end
+
+      # Returns true if this language supports the given feature (e.g. 'formality').
+      def supports?(feature)
+        features.key?(feature.to_s)
+      end
+    end
+  end
+end