deepl-rb 3.9.0 → 3.10.0

data/lib/deepl/requests/admin/base.rb

@@ -0,0 +1,94 @@
+# 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
+
+require 'date'
+
+module DeepL
+  module Requests
+    module Admin
+      class Base < Requests::Base
+        def initialize(api, extra_body_parameters = nil)
+          options = {}
+          options[:extra_body_parameters] = extra_body_parameters unless extra_body_parameters.nil?
+          super(api, options)
+        end
+
+        def to_s
+          "#{http_method} #{uri.request_uri}"
+        end
+
+        private
+
+        def http_method
+          'GET'
+        end
+
+        def get_request # rubocop:disable Naming/AccessorMethodName
+          Net::HTTP::Get.new(uri.request_uri, add_json_content_type(headers))
+        end
+
+        def uri
+          @uri ||= begin
+            base_uri = URI(url)
+            query_string = encode_query(query_params)
+            base_uri.query = query_string unless query_string.empty?
+            base_uri
+          end
+        end
+
+        def query_params
+          {}
+        end
+
+        def date_range_params(start_date, end_date)
+          start_day = parse_date(start_date)
+          end_day = parse_date(end_date)
+
+          { 'start_date' => start_day.iso8601, 'end_date' => end_day.iso8601 }
+        end
+
+        def parse_date(value)
+          return value.new_offset(0).to_date if value.is_a?(DateTime)
+          return value if value.is_a?(Date)
+          return value.getutc.to_date if value.is_a?(Time)
+
+          date = parse_date_string(value) if value.is_a?(String)
+          return date if date
+
+          raise ArgumentError,
+                "Invalid date #{value.inspect}, expected a Date, a Time, a DateTime or " \
+                'a YYYY-MM-DD string'
+        end
+
+        def parse_date_string(value)
+          return nil unless value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+
+          year, month, day = value.split('-').map(&:to_i)
+          Date.new(year, month, day) if Date.valid_date?(year, month, day)
+        end
+
+        def build_developer_key(request, response)
+          data = JSON.parse(response.body)
+          raise DeepL::Exceptions::Error, 'Developer key response is missing key_id' unless
+            usable_developer_key?(data)
+
+          Resources::DeveloperKey.new(data, request, response)
+        end
+
+        def usable_developer_key?(data)
+          data.is_a?(Hash) && data['key_id'].is_a?(String) && !data['key_id'].empty?
+        end
+
+        def parse_json_object(response)
+          data = JSON.parse(response.body)
+          raise DeepL::Exceptions::Error, 'Analytics response is not a JSON object' unless
+            data.is_a?(Hash)
+
+          data
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/admin/create_developer_key.rb

@@ -0,0 +1,38 @@
+# 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
+    module Admin
+      class CreateDeveloperKey < Base
+        def initialize(api, label = nil, extra_body_parameters = nil)
+          super(api, extra_body_parameters)
+          @label = label
+        end
+
+        def request
+          payload = {}
+          payload[:label] = @label unless @label.nil?
+          build_developer_key(*execute_request_with_retries(post_request(payload)))
+        end
+
+        private
+
+        def http_method
+          'POST'
+        end
+
+        def path
+          'admin/developer-keys'
+        end
+
+        # A repeated creation request could create a second key.
+        def retry_only_unprocessed?
+          true
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/admin/custom_tag_usage_analytics.rb

@@ -0,0 +1,38 @@
+# 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
+    module Admin
+      class CustomTagUsageAnalytics < Base
+        def initialize(api, start_date, end_date, aggregate_by = nil, page = nil)
+          super(api)
+          @start_date = start_date
+          @end_date = end_date
+          @aggregate_by = aggregate_by
+          @page = page
+        end
+
+        def request
+          request, response = execute_request_with_retries(get_request)
+          Resources::CustomTagUsageReport.new(parse_json_object(response), request, response)
+        end
+
+        private
+
+        def query_params
+          params = date_range_params(@start_date, @end_date)
+          params['aggregate_by'] = @aggregate_by.to_s unless @aggregate_by.nil?
+          params['page'] = @page.to_s unless @page.nil?
+          params
+        end
+
+        def path
+          'admin/analytics/custom-tags'
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/admin/list_developer_keys.rb

@@ -0,0 +1,28 @@
+# 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
+    module Admin
+      class ListDeveloperKeys < Base
+        def request
+          request, response = execute_request_with_retries(get_request)
+          keys = JSON.parse(response.body)
+          raise DeepL::Exceptions::Error, 'Developer key list response is not a JSON array' unless
+            keys.is_a?(Array)
+
+          keys.select { |key| usable_developer_key?(key) }
+              .map { |key| Resources::DeveloperKey.new(key, request, response) }
+        end
+
+        private
+
+        def path
+          'admin/developer-keys'
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/admin/update_developer_key.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
+    module Admin
+      ##
+      # Sends a PUT to +admin/developer-keys/<action>+. The payload is sent as is, so +nil+
+      # values are serialized as explicit JSON nulls; +extra_body_parameters+ are added last.
+      class UpdateDeveloperKey < Base
+        def initialize(api, action, payload, extra_body_parameters = nil)
+          super(api, extra_body_parameters)
+          @action = action
+          @payload = payload
+        end
+
+        def request
+          build_developer_key(*execute_request_with_retries(put_request(@payload.dup)))
+        end
+
+        private
+
+        def http_method
+          'PUT'
+        end
+
+        def path
+          "admin/developer-keys/#{@action}"
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/admin/usage_analytics.rb

@@ -0,0 +1,36 @@
+# 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
+    module Admin
+      class UsageAnalytics < Base
+        def initialize(api, start_date, end_date, group_by = nil)
+          super(api)
+          @start_date = start_date
+          @end_date = end_date
+          @group_by = group_by
+        end
+
+        def request
+          request, response = execute_request_with_retries(get_request)
+          Resources::AdminUsageReport.new(parse_json_object(response), request, response)
+        end
+
+        private
+
+        def query_params
+          params = date_range_params(@start_date, @end_date)
+          params['group_by'] = @group_by.to_s unless @group_by.nil?
+          params
+        end
+
+        def path
+          'admin/analytics'
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/base.rb

@@ -9,6 +9,41 @@ module DeepL
       # Maximum number of glossaries that may be provided via the +glossary_ids+ option.
       MAX_GLOSSARY_IDS = 5
 
+      # Transient network failures, which are retried: DNS (SocketError), timeouts
+      # (Net::OpenTimeout and Net::ReadTimeout are Timeout::Errors), refused or reset connections,
+      # broken pipes and unreachable hosts (SystemCallError), and connections closed early.
+      RETRYABLE_NETWORK_ERRORS = [Timeout::Error, SocketError, SystemCallError, EOFError].freeze
+
+      # Network failures without an HTTP response from the API. TLS failures, malformed responses
+      # and proxy failures (Net::ProtocolError, raised when a proxy refuses CONNECT, e.g. with 407)
+      # are not transient and are raised without retrying.
+      NETWORK_ERRORS = [*RETRYABLE_NETWORK_ERRORS, Net::HTTPBadResponse,
+                        OpenSSL::SSL::SSLError, Net::ProtocolError].freeze
+
+      # Errors raised while building the result from a received response: the response has an
+      # unexpected format.
+      RESPONSE_FORMAT_ERRORS = [JSON::ParserError, NoMethodError, TypeError, KeyError].freeze
+
+      # Headers that describe the request the SDK builds; a caller's value is dropped.
+      TECHNICAL_HEADERS = %w[content-type content-length transfer-encoding host].freeze
+
+      # Wraps +request+ of every request class, so that a malformed response raises a
+      # DeepL::Exceptions::Error instead of a raw JSON or type error.
+      module ResponseFormatGuard
+        def request
+          super
+        rescue *RESPONSE_FORMAT_ERRORS => e
+          raise e unless @response_received
+
+          raise Exceptions::Error, "Unexpected response from the DeepL API: #{e.message}"
+        end
+      end
+
+      def self.inherited(subclass)
+        super
+        subclass.prepend(ResponseFormatGuard)
+      end
+
       attr_reader :api, :response, :options
 
       def initialize(api, options = {}, additional_headers = {})
@@ -24,7 +59,7 @@ module DeepL
       end
 
       def details
-        "HTTP Headers #{headers}"
+        "HTTP Headers #{loggable_headers}"
       end
 
       private
@@ -34,11 +69,15 @@ module DeepL
       end
 
       def option(name)
-        options[name.to_s] || options[name.to_sym]
+        return options[name.to_s] if options.key?(name.to_s)
+
+        options[name.to_sym]
       end
 
       def delete_option(name)
-        options.delete(name.to_s) || options.delete(name.to_sym)
+        return options.delete(name.to_s) if options.key?(name.to_s)
+
+        options.delete(name.to_sym)
       end
 
       def set_option(name, value)
@@ -64,7 +103,7 @@ module DeepL
 
         extra_params = option(:extra_body_parameters)
         extra_params.each do |key, value|
-          payload[key] = value
+          payload[key.to_s] = value
         end
       end
 
@@ -88,47 +127,116 @@ module DeepL
         api.configuration.logger&.info("Request to the DeepL API: #{self}")
         api.configuration.logger&.debug("Request details: #{details}")
         loop do
-          resp = http_client.request(req)
-          validate_response!(resp)
+          resp = nil
+          client = http_client
+          apply_request_timeout(client)
+          resp = client.request(req) { |response| read_complete_body(response) }
+          validate_response!(resp, req)
+          @response_received = true
           return [req, resp]
         rescue DeepL::Exceptions::Error => e
           raise e unless should_retry?(resp, e, @backoff_timer.num_retries)
 
-          unless e.nil?
-            api.configuration.logger&.info("Encountered a retryable exception: #{e.message}")
-          end
-          api.configuration.logger&.info("Starting retry #{@backoff_timer.num_retries + 1} for " \
-                                         "request #{self} after sleeping for " \
-                                         "#{format('%.2f', @backoff_timer.time_until_deadline)}")
-          files_to_reset.each(&:rewind)
-          @backoff_timer.sleep_until_deadline
+          wait_before_retry(e, files_to_reset)
           next
-        rescue Net::HTTPBadResponse, Net::HTTPServerError, Net::HTTPFatalError, Timeout::Error,
-               SocketError => e
-          unless e.nil?
-            api.configuration.logger&.info("Encountered a retryable exception: #{e.message}")
-          end
-          api.configuration.logger&.info("Starting retry #{@backoff_timer.num_retries + 1} for " \
-                                         "request #{self} after sleeping for " \
-                                         "#{format('%.2f', @backoff_timer.time_until_deadline)}")
-          files_to_reset.each(&:rewind)
-          @backoff_timer.sleep_until_deadline
+        rescue *NETWORK_ERRORS => e
+          raise_network_error(e) unless retry_network_error?(e)
+
+          wait_before_retry(e, files_to_reset)
           next
         end
       end
 
+      # Until the next major version, the module-level API raises the original network error.
+      def raise_network_error(error)
+        if api.client?
+          raise Exceptions::ConnectionError.from_network_error(
+            error, should_retry: !retry_only_unprocessed? || unprocessed_error?(error)
+          )
+        end
+
+        raise error
+      end
+
+      # Before net-http 0.3, Net::HTTP cannot raise at EOF of a short body (+ignore_eof+), so the
+      # body is compared with Content-Length. An inflated body has no comparable length.
+      def read_complete_body(response)
+        encoding = response['content-encoding']
+        expected = response.content_length unless response.chunked?
+        body = response.read_body
+        return if body.nil? || expected.nil? || !(encoding.nil? || encoding == 'identity')
+        return if body.bytesize >= expected
+
+        raise EOFError, "Response body ended after #{body.bytesize} of #{expected} bytes"
+      end
+
+      # Per attempt, the timeout is the configured timeout or, if longer, the time until the
+      # backoff deadline. Timeouts given in HTTPClientOptions take precedence.
+      def apply_request_timeout(client) # rubocop:disable Metrics/AbcSize
+        timeout = api.configuration.timeout
+        return if timeout.nil? || !client.respond_to?(:read_timeout=)
+
+        timeout = [timeout.to_f, @backoff_timer.time_until_deadline].max
+        options = http_client_options_of(client)
+        client.open_timeout = timeout if options&.open_timeout.nil?
+        client.read_timeout = timeout if options&.read_timeout.nil?
+        client.write_timeout = timeout if options&.write_timeout.nil?
+      end
+
+      # The HTTPClientOptions +client+ was built with, if any.
+      def http_client_options_of(client)
+        client.equal?(api.http_client) ? api.http_client_options : nil
+      end
+
+      def wait_before_retry(error, files_to_reset)
+        logger = api.configuration.logger
+        logger&.info("Encountered a retryable exception: #{error.message}")
+        logger&.info("Starting retry #{@backoff_timer.num_retries + 1} for " \
+                     "request #{self} after sleeping for " \
+                     "#{format('%.2f', @backoff_timer.time_until_deadline)}")
+        files_to_reset.each(&:rewind)
+        @backoff_timer.sleep_until_deadline
+      end
+
+      def retry_network_error?(error)
+        Exceptions::ConnectionError.transient?(error) &&
+          @backoff_timer.num_retries < api.configuration.max_network_retries &&
+          (!retry_only_unprocessed? || unprocessed_error?(error))
+      end
+
       def should_retry?(response, exception, num_retries)
         return false if num_retries >= api.configuration.max_network_retries
         return exception.should_retry? if response.nil?
 
-        response.is_a?(Net::HTTPTooManyRequests) || response.is_a?(Net::HTTPInternalServerError)
+        return response.is_a?(Net::HTTPTooManyRequests) if retry_only_unprocessed?
+
+        response.is_a?(Net::HTTPTooManyRequests) || (500..599).cover?(response.code.to_i)
+      end
+
+      # Requests that are unsafe to repeat return true to retry only failures that show the
+      # request was not processed: HTTP 429, DNS resolution errors (SocketError), refused
+      # connections and connection timeouts (Net::OpenTimeout).
+      def retry_only_unprocessed?
+        false
+      end
+
+      def unprocessed_error?(error)
+        error.is_a?(SocketError) || error.is_a?(Net::OpenTimeout) ||
+          error.is_a?(Errno::ECONNREFUSED)
+      end
+
+      # The request body: the SDK's payload, then the options, then +extra_body_parameters+,
+      # which replace an SDK field of the same name.
+      def json_body(payload)
+        body = payload.merge(options_without_extra_params).transform_keys(&:to_s)
+        apply_extra_body_parameters_to_json(body)
+        body.to_json
       end
 
       def post_request(payload)
-        apply_extra_body_parameters_to_json(payload)
         http_headers = add_json_content_type(headers)
         post_req = Net::HTTP::Post.new(uri.path, http_headers)
-        post_req.body = payload.merge(options_without_extra_params).to_json
+        post_req.body = json_body(payload)
         post_req
       end
 
@@ -139,89 +247,131 @@ module DeepL
         post_req
       end
 
+      # GET and DELETE send no body, so no Content-Type either.
       def get_request # rubocop:disable Naming/AccessorMethodName
-        http_headers = add_json_content_type(headers)
-        get_req = Net::HTTP::Get.new(uri.path, http_headers)
-        get_req.body = options_without_extra_params.to_json
-        get_req
+        Net::HTTP::Get.new(uri.path, headers)
       end
 
       def patch_request(payload)
-        apply_extra_body_parameters_to_json(payload)
         http_headers = add_json_content_type(headers)
         req = Net::HTTP::Patch.new(uri.path, http_headers)
-        req.body = payload.merge(options_without_extra_params).to_json
+        req.body = json_body(payload)
         req
       end
 
       def put_request(payload)
-        apply_extra_body_parameters_to_json(payload)
         http_headers = add_json_content_type(headers)
         req = Net::HTTP::Put.new(uri.path, http_headers)
-        req.body = payload.merge(options_without_extra_params).to_json
+        req.body = json_body(payload)
         req
       end
 
       def delete_request
-        http_headers = add_json_content_type(headers)
-        del_req = Net::HTTP::Delete.new(uri.path, http_headers)
-        del_req.body = options_without_extra_params.to_json
-        del_req
+        Net::HTTP::Delete.new(uri.path, headers)
       end
 
-      def validate_response!(response)
+      def validate_response!(response, request = nil)
         return if response.is_a?(Net::HTTPSuccess)
+        # A request that is unsafe to repeat may have been processed before the server failed.
+        if retry_only_unprocessed? && (500..599).cover?(response.code.to_i)
+          raise Exceptions::ServerError.new(response, request, should_retry: false)
+        end
 
-        raise Utils::ExceptionBuilder.new(response).build
+        raise Utils::ExceptionBuilder.new(response, request).build
       end
 
       # Validates the +glossary_ids+ option and resolves it to an array of glossary ID strings.
       #
       # The +glossary_ids+ option accepts an array of up to `MAX_GLOSSARY_IDS` glossary
-      # identifiers. Each entry may be a glossary ID string or a
-      # `DeepL::Resources::Glossary` object. It:
-      # * requires +source_lang+ to be set,
-      # * cannot be combined with the singular +glossary_id+ option,
+      # identifiers. Each entry may be a glossary ID string, a
+      # `DeepL::Resources::Glossary` or a `DeepL::Resources::MultilingualGlossary` object. It:
+      # * cannot be combined with the singular +glossary+ or +glossary_id+ option,
       # * allows at most `MAX_GLOSSARY_IDS` identifiers.
       #
       # The API expects +glossary_ids+ as an array (a JSON array in the JSON translate body).
       # Callers sending multipart/form-data (e.g. document upload) should join the returned
       # array into a comma-separated string.
       #
-      # @param [String, nil] source_lang The source language for the request.
       # @return [Array<String>, nil] The list of glossary IDs, or nil if the +glossary_ids+
       #                              option was not provided.
       # @raise [ArgumentError] If any of the validation rules above are violated.
-      def build_glossary_ids_param(source_lang)
+      def build_glossary_ids_param
         return nil unless option?(:glossary_ids)
 
         ids = Array(delete_option(:glossary_ids))
         return nil if ids.empty?
 
-        validate_glossary_ids!(ids, source_lang)
-        ids.map do |glossary|
-          glossary.is_a?(DeepL::Resources::Glossary) ? glossary.id : glossary.to_s
-        end
+        validate_glossary_ids!(ids)
+        ids.map { |glossary| glossary_id_string(glossary) }
       end
 
-      def validate_glossary_ids!(ids, source_lang)
-        if option?(:glossary_id)
+      # Resolves the +glossary+ option (a glossary ID string, a `DeepL::Resources::Glossary` or
+      # a `DeepL::Resources::MultilingualGlossary`) to the ID sent as +glossary_id+, and warns
+      # about the deprecated +glossary_id+ option.
+      #
+      # @return [String, nil] The glossary ID, or nil if the +glossary+ option is unset.
+      # @raise [ArgumentError] If +glossary+ is combined with +glossary_id+.
+      def build_glossary_param
+        warn_glossary_id_deprecated unless option(:glossary_id).nil?
+        return nil unless option?(:glossary)
+
+        glossary = delete_option(:glossary)
+        return nil if glossary.nil?
+
+        unless option(:glossary_id).nil?
           raise ArgumentError,
-                'The `glossary_ids` option cannot be used together with the `glossary_id` option'
-        end
-        if source_lang.nil?
-          raise ArgumentError, 'The `glossary_ids` option requires `source_lang` to be set'
+                'The `glossary` option cannot be used together with the `glossary_id` option'
         end
+        glossary_id_string(glossary)
+      end
+
+      def warn_glossary_id_deprecated
+        Deprecation.warn_once_at_caller(
+          'option glossary_id',
+          '[DEPRECATION] The glossary_id option is deprecated, use the glossary option instead.'
+        )
+      end
+
+      def glossary_id_string(glossary)
+        return glossary.id if glossary.is_a?(DeepL::Resources::Glossary)
+        return glossary.id if glossary.is_a?(DeepL::Resources::MultilingualGlossary)
+
+        glossary.to_s
+      end
+
+      def validate_glossary_ids!(ids)
+        validate_no_single_glossary!
         return unless ids.size > MAX_GLOSSARY_IDS
 
         raise ArgumentError,
               "A maximum of #{MAX_GLOSSARY_IDS} glossary IDs may be provided via `glossary_ids`"
       end
 
+      def validate_no_single_glossary!
+        single = if !option(:glossary).nil? then 'glossary'
+                 elsif !option(:glossary_id).nil? then 'glossary_id'
+                 end
+        return unless single
+
+        raise ArgumentError,
+              "The `glossary_ids` option cannot be used together with the `#{single}` option"
+      end
+
       def path
         raise NotImplementedError
       end
 
+      # URL-encodes a value for use as one path segment (a space as %20, not +).
+      def escape_path_segment(value)
+        URI.encode_www_form_component(value.to_s).gsub('+', '%20')
+      end
+
+      # URL-encodes +params+ as a query string per RFC 3986. encode_www_form writes a space as +,
+      # which is right for a form body only; a literal + is already %2B, so every + is a space.
+      def encode_query(params)
+        URI.encode_www_form(params).gsub('+', '%20')
+      end
+
       def url
         "#{host}/#{api.configuration.version}/#{path}"
       end
@@ -245,9 +395,29 @@ module DeepL
         options
       end
 
+      # The configured +headers+, then the per-call additional headers, each replace a header of
+      # the same name in any casing, Authorization and User-Agent included.
       def headers
-        { 'Authorization' => "DeepL-Auth-Key #{api.configuration.auth_key}",
-          'User-Agent' => api.configuration.user_agent }.merge(@additional_headers)
+        library = { 'Authorization' => "DeepL-Auth-Key #{api.configuration.auth_key.to_s.strip}",
+                    'User-Agent' => api.configuration.user_agent }
+        merge_headers(library, api.configuration.headers, @additional_headers)
+      end
+
+      def merge_headers(base, *given_headers)
+        given_headers.each_with_object(base) do |given, merged|
+          (given || {}).each do |name, value|
+            next if TECHNICAL_HEADERS.include?(name.to_s.downcase)
+
+            merged.delete_if { |existing, _| existing.to_s.casecmp?(name.to_s) }
+            merged[name] = value
+          end
+        end
+      end
+
+      def loggable_headers
+        headers.to_h do |name, value|
+          name.to_s.casecmp?('authorization') ? [name, 'DeepL-Auth-Key [REDACTED]'] : [name, value]
+        end
       end
 
       def add_json_content_type(headers_to_add_to)