deepl-rb 3.9.0 → 3.10.0

data/Rakefile

@@ -34,10 +34,13 @@ Juwelier::Tasks.new do |gem|
     'homepage_uri' => 'https://github.com/DeepLcom/deepl-rb'
   }
   gem.files.exclude '.bumpversion.toml'
-  gem.files.exclude '.devcontainer/**/*'
-  gem.files.exclude '.github'
-  gem.files.exclude '.circleci'
+  gem.files.exclude '.github/**/*'
+  gem.files.exclude '.circleci/**/*'
   gem.files.exclude 'catalog-info.yaml'
+  gem.files.exclude '.auto-approve.yaml'
+  gem.files.exclude '.gitar/**/*'
+  gem.files.exclude '.releaserc.mjs'
+  gem.files.exclude 'renovate.json5'
 end
 
 Juwelier::RubygemsDotOrgTasks.new
@@ -47,9 +50,19 @@ require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
-RSpec::Core::RakeTask.new(:spec)
 
-desc 'Run all tests.'
+namespace :spec do
+  desc 'Run the offline specs: no network, no key.'
+  RSpec::Core::RakeTask.new(:offline) { |task| task.pattern = 'spec/offline/**/*_spec.rb' }
+
+  desc 'Run the real-API specs: needs DEEPL_AUTH_KEY, sends real requests.'
+  RSpec::Core::RakeTask.new(:real_api) { |task| task.pattern = 'spec/real_api/**/*_spec.rb' }
+end
+
+desc 'Run the offline specs.'
+task spec: 'spec:offline'
+
+desc 'Run the offline specs and rubocop.'
 task :test do
   Rake::Task['spec'].invoke
   Rake::Task['rubocop'].invoke

data/VERSION

@@ -1 +1 @@
-3.9.0
+3.10.0

data/deepl-rb.gemspec

@@ -2,17 +2,17 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Juwelier::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: deepl-rb 3.9.0 ruby lib
+# stub: deepl-rb 3.10.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "deepl-rb".freeze
-  s.version = "3.9.0"
+  s.version = "3.10.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.metadata = { "bug_tracker_uri" => "https://github.com/DeepLcom/deepl-rb/issues", "changelog_uri" => "https://github.com/DeepLcom/deepl-rb/blob/main/CHANGELOG.md", "documentation_uri" => "https://github.com/DeepLcom/deepl-rb/blob/main/README.md", "homepage_uri" => "https://github.com/DeepLcom/deepl-rb" } if s.respond_to? :metadata=
   s.require_paths = ["lib".freeze]
   s.authors = ["DeepL SE".freeze]
-  s.date = "2026-08-12"
+  s.date = "2026-08-11"
   s.description = "Official Ruby library for the DeepL language translation API (v2). For more information, check this: https://www.deepl.com/docs/api-reference.html".freeze
   s.email = "open-source@deepl.com".freeze
   s.extra_rdoc_files = [
@@ -189,12 +189,12 @@ Gem::Specification.new do |s|
   ]
   s.homepage = "https://github.com/DeepLcom/deepl-rb".freeze
   s.licenses = ["MIT".freeze]
-  s.rubygems_version = "3.4.10".freeze
+  s.rubygems_version = "3.6.2".freeze
   s.summary = "Official Ruby library for the DeepL language translation API.".freeze
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<juwelier>.freeze, [">= 0"])
-  s.add_development_dependency(%q<byebug>.freeze, [">= 0"])
+  s.add_development_dependency(%q<juwelier>.freeze, [">= 0".freeze])
+  s.add_development_dependency(%q<byebug>.freeze, [">= 0".freeze])
 end
 

data/lib/deepl/admin_client.rb

@@ -0,0 +1,183 @@
+# 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
+  ##
+  # Client for the DeepL Admin API, used to manage the developer keys of your organization and
+  # to retrieve usage analytics. It is independent of +DeepL.configure+ and never reads the
+  # +DEEPL_AUTH_KEY+ or +DEEPL_SERVER_URL+ environment variables.
+  #
+  # All methods may raise a +DeepL::Exceptions::Error+ or a subclass, for example
+  # +DeepL::Exceptions::AuthorizationFailed+ if the admin key is not accepted.
+  class AdminClient
+    DEEPL_SERVER_URL = 'https://api.deepl.com'
+    private_constant :DEEPL_SERVER_URL
+
+    ##
+    # @param [String] admin_key Admin API key, surrounding whitespace is removed.
+    # @param [String, nil] server_url Base URL of the DeepL API, defaults to
+    #   +https://api.deepl.com+ (also for keys ending in +:fx+).
+    # @param [Hash] headers HTTP headers sent with every request. A header of the same name in
+    #   any casing replaces the library's, +Authorization+ and +User-Agent+ included, except the
+    #   technical headers +Content-Type+, +Content-Length+, +Transfer-Encoding+ and +Host+.
+    # @param [Integer] max_retries Number of retries after the first attempt.
+    # @param [Numeric] timeout Timeout of each attempt in seconds.
+    # @param [String, nil] proxy Proxy URL, e.g. +http://user:password@proxy.example:8080+.
+    # @param [Boolean] send_platform_info Whether to send basic platform information.
+    # @param [DeepL::AppInfo, Hash, nil] app_info Your application's +app_name+ and
+    #   +app_version+, added to the +User-Agent+.
+    # @param [DeepL::HTTPClientOptions, nil] http_client_options Proxy, SSL and timeout options.
+    # @param [Logger, nil] logger Logger for requests and retries.
+    # @raise [ArgumentError] If +admin_key+ is empty.
+    def initialize(admin_key, server_url: nil, headers: {}, max_retries: 5, timeout: 10, # rubocop:disable Metrics/ParameterLists
+                   proxy: nil, send_platform_info: true, app_info: nil, http_client_options: nil,
+                   logger: nil)
+      @api = Utils::ClientBuilder.build_api(
+        admin_key, key_name: 'admin_key', server_url: server_url,
+                   default_server_url: DEEPL_SERVER_URL, headers: headers,
+                   max_retries: max_retries, timeout: timeout, proxy: proxy,
+                   send_platform_info: send_platform_info, app_info: app_info,
+                   http_client_options: http_client_options, logger: logger
+      )
+    end
+
+    def inspect
+      "#<#{self.class.name} server_url=#{configuration.host}>"
+    end
+
+    ##
+    # Retrieves the usage of the organization within a date range. The API requires the start date
+    # to be before the end date (a report covers at least two days) and the range to be at most
+    # 366 days.
+    #
+    # @param [Date, Time, DateTime, String] start_date Start date, as a +Date+, a +Time+, a
+    #   +DateTime+ or a +YYYY-MM-DD+ string. Dates are UTC calendar days and both the start and
+    #   the end day are included. For +Time+ and +DateTime+ values the UTC date of that moment is
+    #   sent: +2026-10-20 00:00 +02:00+ is sent as +2026-10-19+.
+    # @param [Date, Time, DateTime, String] end_date End date, in the same format as +start_date+.
+    # @param [String, Symbol, nil] group_by Group the usage by key or by key and day, see
+    #   +DeepL::Constants::AdminUsageGroupBy+ for the accepted values. It is sent as is, and the
+    #   +group_by+ of the report is the raw string the API returns.
+    # @return [DeepL::Resources::AdminUsageReport]
+    # @raise [ArgumentError] If a date is invalid.
+    # @raise [DeepL::Exceptions::BadRequest] If the API rejects the date range.
+    def get_usage_analytics(start_date, end_date, group_by: nil)
+      Requests::Admin::UsageAnalytics.new(api, start_date, end_date, group_by).request
+    end
+
+    ##
+    # Retrieves the usage per custom tag within a date range, with the same limits as
+    # +get_usage_analytics+. Results are paginated: pass the +next_page+ of a report as +page+ to
+    # retrieve the following page.
+    #
+    # @param [Date, Time, DateTime, String] start_date Start date, as a +Date+, a +Time+, a
+    #   +DateTime+ or a +YYYY-MM-DD+ string. Dates are UTC calendar days and both the start and
+    #   the end day are included. For +Time+ and +DateTime+ values the UTC date of that moment is
+    #   sent: +2026-10-20 00:00 +02:00+ is sent as +2026-10-19+.
+    # @param [Date, Time, DateTime, String] end_date End date, in the same format as +start_date+.
+    # @param [String, Symbol, nil] aggregate_by Aggregate the usage over the whole period or by
+    #   day, see +DeepL::Constants::CustomTagUsageAggregateBy+. It is sent as is, and the
+    #   +aggregate_by+ of the report is the raw string the API returns.
+    # @param [Integer, nil] page Page number to retrieve.
+    # @return [DeepL::Resources::CustomTagUsageReport]
+    # @raise [ArgumentError] If a date is invalid.
+    # @raise [DeepL::Exceptions::BadRequest] If the API rejects the date range.
+    def get_custom_tag_usage_analytics(start_date, end_date, aggregate_by: nil, page: nil)
+      Requests::Admin::CustomTagUsageAnalytics.new(api, start_date, end_date, aggregate_by,
+                                                   page).request
+    end
+
+    ##
+    # Creates a developer key. The API uses "DeepL API Key" as label if none is given.
+    #
+    # Creation is retried only after failures that show the request was not processed (HTTP 429,
+    # DNS resolution errors, refused connections and connection timeouts), so that a retry
+    # cannot create a second key. The raised error has +should_retry?+ true only for these.
+    #
+    # @param [String, nil] label Label for the new key, not sent if +nil+.
+    # @param [Hash, nil] extra_body_parameters Added to the request body last; replaces fields
+    #   of the same name. Values are sent as given.
+    # @return [DeepL::Resources::DeveloperKey]
+    def create_developer_key(label: nil, extra_body_parameters: nil)
+      Requests::Admin::CreateDeveloperKey.new(api, label, extra_body_parameters).request
+    end
+
+    ##
+    # Retrieves all developer keys of the organization, including deactivated ones.
+    #
+    # @return [Array<DeepL::Resources::DeveloperKey>]
+    def list_developer_keys
+      Requests::Admin::ListDeveloperKeys.new(api).request
+    end
+
+    ##
+    # Deactivates a developer key. Deactivation is permanent.
+    #
+    # @param [String, DeepL::Resources::DeveloperKey] key Key ID or developer key.
+    # @param [Hash, nil] extra_body_parameters Added to the request body last; replaces fields
+    #   of the same name. Values are sent as given.
+    # @return [DeepL::Resources::DeveloperKey]
+    # @raise [ArgumentError] If the key ID is empty.
+    def deactivate_developer_key(key, extra_body_parameters: nil)
+      update_developer_key('deactivate', { key_id: key_id(key) }, extra_body_parameters)
+    end
+
+    ##
+    # Changes the label of a developer key.
+    #
+    # @param [String, DeepL::Resources::DeveloperKey] key Key ID or developer key.
+    # @param [String] label New label for the key.
+    # @param [Hash, nil] extra_body_parameters Added to the request body last; replaces fields
+    #   of the same name. Values are sent as given.
+    # @return [DeepL::Resources::DeveloperKey]
+    # @raise [ArgumentError] If the key ID is empty.
+    def rename_developer_key(key, label, extra_body_parameters: nil)
+      update_developer_key('label', { key_id: key_id(key), label: label }, extra_body_parameters)
+    end
+
+    ##
+    # Changes the usage limits of a developer key. Only the given limits are changed; omitted
+    # limits keep their current value. A +nil+ limit means unlimited and +0+ blocks that usage.
+    #
+    #   admin_client.set_developer_key_usage_limits(key, characters: 0)
+    #   admin_client.set_developer_key_usage_limits(key, speech_to_text_milliseconds: nil)
+    #
+    # @param [String, DeepL::Resources::DeveloperKey] key Key ID or developer key.
+    # @param [Hash] limits Limits to change: +:characters+ (characters per usage period across
+    #   text translation, document translation and text improvement),
+    #   +:speech_to_text_milliseconds+ and +:speech_to_speech_milliseconds+, each an +Integer+ or
+    #   +nil+. They are sent as is and validated by the API.
+    # @param [Hash, nil] extra_body_parameters Added to the request body last; replaces fields
+    #   of the same name. Values are sent as given.
+    # @return [DeepL::Resources::DeveloperKey]
+    # @raise [ArgumentError] If the key ID is empty.
+    def set_developer_key_usage_limits(key, extra_body_parameters: nil, **limits)
+      update_developer_key('limits', limits.merge(key_id: key_id(key)), extra_body_parameters)
+    end
+
+    private
+
+    attr_reader :api
+
+    def configuration
+      api.configuration
+    end
+
+    def update_developer_key(action, payload, extra_body_parameters)
+      Requests::Admin::UpdateDeveloperKey.new(api, action, payload, extra_body_parameters).request
+    end
+
+    def key_id(key)
+      id = key.is_a?(Resources::DeveloperKey) ? key.key_id : key
+      raise ArgumentError, 'key ID must not be empty' if blank?(id)
+
+      id
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+  end
+end

data/lib/deepl/api.rb

@@ -5,18 +5,42 @@
 
 module DeepL
   class API
-    attr_reader :configuration, :http_client
+    attr_reader :configuration, :http_client, :http_client_options
 
-    def initialize(configuration)
+    # +client:+ is true for the API of a DeepL::Client or DeepL::AdminClient, whose errors differ
+    # from those of the module-level API until the next major version. @api private
+    def initialize(configuration, http_client_options = nil, client: false)
       @configuration = configuration
+      @client = client
       configuration.validate!
-      uri = URI(configuration.host)
-      @http_client = Net::HTTP.new(uri.host, uri.port)
-      @http_client.use_ssl = uri.scheme == 'https'
+      @http_client_options = http_client_options
+      @http_client = if http_client_options
+                       Utils::HTTPClientBuilder.build(configuration.host, http_client_options)
+                     else
+                       default_http_client(configuration.host)
+                     end
     end
 
-    def update_http_client(client)
+    # @api private
+    def client?
+      @client
+    end
+
+    # +options+ are the HTTPClientOptions the client was built with; their timeouts take
+    # precedence over the per-attempt timeout.
+    def update_http_client(client, options = nil)
       @http_client = client
+      @http_client_options = options
+    end
+
+    private
+
+    # Without explicit options Net::HTTP applies the proxy from the environment (+http_proxy+).
+    def default_http_client(host)
+      uri = URI(host)
+      client = Net::HTTP.new(uri.host, uri.port)
+      client.use_ssl = uri.scheme == 'https'
+      Utils::HTTPClientBuilder.disable_lenient_defaults(client)
     end
   end
 end

data/lib/deepl/app_info.rb

@@ -0,0 +1,20 @@
+# 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
+  ##
+  # Identifies your application in the +User-Agent+ header as +<app_name>/<app_version>+.
+  AppInfo = Struct.new(:app_name, :app_version, keyword_init: true) do
+    # Accepts an AppInfo or a hash with +:app_name+ and +:app_version+.
+    def self.from(value)
+      return nil if value.nil?
+      return value if value.is_a?(AppInfo)
+      raise ArgumentError, 'app_info must be a DeepL::AppInfo or a Hash' unless value.is_a?(Hash)
+
+      new(app_name: value[:app_name] || value['app_name'],
+          app_version: value[:app_version] || value['app_version'])
+    end
+  end
+end