deepl-rb 3.7.0 → 3.9.0

data/spec/requests/translation_memory/segments_spec.rb

@@ -0,0 +1,58 @@
+# 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 'spec_helper'
+
+describe DeepL::Requests::TranslationMemory::Segments do
+  subject(:translation_memory_segments) { described_class.new(api, id, options) }
+
+  around do |tests|
+    tmp_env = replace_env_preserving_deepl_vars_except_mock_server
+    tests.call
+    ENV.replace(tmp_env)
+  end
+
+  let(:api) { build_deepl_api }
+  let(:id) { 'a74d88fb-ed2a-4943-a664-a4512398b994' }
+  let(:options) { {} }
+
+  describe '#initialize' do
+    context 'when building a request' do
+      it 'creates a request object' do
+        expect(translation_memory_segments).to be_a(described_class)
+      end
+    end
+  end
+
+  describe '#to_s' do
+    context 'when no options are given' do
+      it 'requests the segments below the v3 prefix without a query string' do
+        expect(translation_memory_segments.to_s)
+          .to eq("GET /v3/translation_memories/#{id}/segments")
+      end
+    end
+
+    context 'when the supported options are given' do
+      let(:options) { { page_size: 10, page_cursor: 'NQ', filter_case_sensitive: true } }
+
+      it 'adds the options to the query string' do
+        expect(translation_memory_segments.to_s)
+          .to eq("GET /v3/translation_memories/#{id}/segments" \
+                 '?page_size=10&page_cursor=NQ&filter_case_sensitive=true')
+      end
+    end
+
+    context 'when the text filter contains characters that must be escaped' do
+      let(:options) { { filter_text: 'a b+c' } }
+
+      # A space must be percent-encoded in a URI query string; `+` only means a space in a form
+      # body, and a literal `+` has to survive as %2B.
+      it 'percent-encodes the spaces instead of writing them as a plus' do
+        expect(translation_memory_segments.to_s)
+          .to eq("GET /v3/translation_memories/#{id}/segments?filter_text=a%20b%2Bc")
+      end
+    end
+  end
+end

data/spec/requests/translation_memory/upload_file_spec.rb

@@ -0,0 +1,55 @@
+# 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 'spec_helper'
+
+describe DeepL::Requests::TranslationMemory::UploadFile do
+  subject(:upload_file) { described_class.new(api, upload_url, file_content) }
+
+  around do |tests|
+    tmp_env = replace_env_preserving_deepl_vars_except_mock_server
+    tests.call
+    ENV.replace(tmp_env)
+  end
+
+  let(:api) { build_deepl_api }
+  let(:upload_url) { 'https://storage.example.com/upload/tm?signature=abc' }
+  let(:file_content) { '<tmx version="1.4"/>' }
+
+  describe '#initialize' do
+    context 'when building a request' do
+      it 'creates a request object' do
+        expect(upload_file).to be_a(described_class)
+        expect(upload_file.content_type).to eq(described_class::DEFAULT_CONTENT_TYPE)
+      end
+    end
+
+    context 'when no upload URL is given' do
+      let(:upload_url) { '' }
+
+      it 'raises an error' do
+        expect { upload_file }.to raise_error(DeepL::Exceptions::Error, /must not be empty/)
+      end
+    end
+  end
+
+  describe '#to_s' do
+    context 'when building a request' do
+      it 'puts to the pre-signed storage URL' do
+        expect(upload_file.to_s).to eq('PUT /upload/tm?signature=abc')
+      end
+    end
+  end
+
+  describe '#details' do
+    context 'when building a request' do
+      # The upload URL points outside of the DeepL API, so the auth key must not be sent there.
+      it 'does not send the DeepL authorization header' do
+        expect(upload_file.details).not_to include('Authorization')
+        expect(upload_file.details).to include('User-Agent')
+      end
+    end
+  end
+end

data/spec/requests/usage_spec.rb

@@ -24,20 +24,4 @@ describe DeepL::Requests::Usage do
       end
     end
   end
-
-  describe '#request' do
-    around do |example|
-      VCR.use_cassette('usage') { example.call }
-    end
-
-    context 'when performing a valid request' do
-      it 'returns an usage object' do
-        usage = usage_req.request
-
-        expect(usage).to be_a(DeepL::Resources::Usage)
-        expect(usage.character_count).to be_a(Numeric)
-        expect(usage.character_limit).to be_a(Numeric)
-      end
-    end
-  end
 end

data/spec/resources/custom_instruction_spec.rb

@@ -0,0 +1,32 @@
+# 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 'spec_helper'
+
+describe DeepL::Resources::CustomInstruction do
+  subject(:custom_instruction) do
+    described_class.new({
+                          'id' => 'ci-1',
+                          'label' => 'Formal',
+                          'prompt' => 'Always use formal language',
+                          'source_language' => 'en'
+                        })
+  end
+
+  describe '#initialize' do
+    context 'when building a basic object' do
+      it 'creates a resource' do
+        expect(custom_instruction).to be_a(described_class)
+      end
+
+      it 'assigns the attributes' do
+        expect(custom_instruction.id).to eq('ci-1')
+        expect(custom_instruction.label).to eq('Formal')
+        expect(custom_instruction.prompt).to eq('Always use formal language')
+        expect(custom_instruction.source_language).to eq('en')
+      end
+    end
+  end
+end

data/spec/resources/style_rule_spec.rb

@@ -0,0 +1,68 @@
+# 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 'spec_helper'
+
+describe DeepL::Resources::StyleRule do
+  subject(:style_rule) do
+    described_class.new({
+                          'style_id' => 'dca2e053-8ae5-45e6-a0d2-881156e7f4e4',
+                          'name' => 'Default Style Rule',
+                          'creation_time' => '2025-01-01T00:00:00Z',
+                          'updated_time' => '2025-01-02T00:00:00Z',
+                          'language' => 'en',
+                          'version' => 1
+                        }, nil, nil)
+  end
+
+  describe '#initialize' do
+    context 'when building a basic object' do
+      it 'creates a resource' do
+        expect(style_rule).to be_a(described_class)
+      end
+
+      it 'assigns the attributes' do
+        expect(style_rule.style_id).to eq('dca2e053-8ae5-45e6-a0d2-881156e7f4e4')
+        expect(style_rule.name).to eq('Default Style Rule')
+        expect(style_rule.language).to eq('en')
+        expect(style_rule.version).to eq(1)
+        expect(style_rule.creation_time).to eq(Time.parse('2025-01-01T00:00:00Z'))
+        expect(style_rule.updated_time).to eq(Time.parse('2025-01-02T00:00:00Z'))
+        expect(style_rule.configured_rules).to be_nil
+        expect(style_rule.custom_instructions).to be_nil
+      end
+    end
+
+    context 'when building an object with configured rules and custom instructions' do
+      subject(:style_rule) do
+        described_class.new({
+                              'style_id' => 'dca2e053-8ae5-45e6-a0d2-881156e7f4e4',
+                              'name' => 'Detailed Style Rule',
+                              'language' => 'en',
+                              'version' => 1,
+                              'configured_rules' => {
+                                'dates_and_times' => { 'calendar_era' => 'use_bc_and_ad' }
+                              },
+                              'custom_instructions' => [
+                                { 'id' => 'ci-1', 'label' => 'Test', 'prompt' => 'Be formal' }
+                              ]
+                            }, nil, nil)
+      end
+
+      it 'maps configured_rules into a ConfiguredRules resource' do
+        expect(style_rule.configured_rules).to be_a(DeepL::Resources::ConfiguredRules)
+        expect(style_rule.configured_rules.dates_and_times)
+          .to eq({ 'calendar_era' => 'use_bc_and_ad' })
+      end
+
+      it 'maps custom_instructions into an array of CustomInstruction resources' do
+        expect(style_rule.custom_instructions).to all(be_a(DeepL::Resources::CustomInstruction))
+        expect(style_rule.custom_instructions.first.id).to eq('ci-1')
+        expect(style_rule.custom_instructions.first.label).to eq('Test')
+        expect(style_rule.custom_instructions.first.prompt).to eq('Be formal')
+      end
+    end
+  end
+end

data/spec/resources/translation_memory_export_spec.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
+
+require 'spec_helper'
+
+describe DeepL::Resources::TranslationMemoryExport do
+  subject(:translation_memory_export) { described_class.new(response, false, nil, nil) }
+
+  let(:response) do
+    {
+      'job_id' => '5b1a0a52-1f3b-4b7f-9f6b-9d4d3f5b6c7d',
+      'parameters' => { 'translation_memory_id' => 'a74d88fb-ed2a-4943-a664-a4512398b994' }
+    }
+  end
+
+  describe '#initialize' do
+    it 'creates a resource' do
+      expect(translation_memory_export).to be_a(described_class)
+    end
+
+    it 'assigns the attributes of a newly created export' do
+      expect(translation_memory_export.job_id).to eq('5b1a0a52-1f3b-4b7f-9f6b-9d4d3f5b6c7d')
+      expect(translation_memory_export.translation_memory_id)
+        .to eq('a74d88fb-ed2a-4943-a664-a4512398b994')
+      expect(translation_memory_export.reused_existing?).to be(false)
+    end
+
+    context 'when the API reused a previously completed export' do
+      subject(:translation_memory_export) { described_class.new(response, true, nil, nil) }
+
+      it 'reports the export as reused' do
+        expect(translation_memory_export.reused_existing?).to be(true)
+      end
+    end
+  end
+end

data/spec/resources/translation_memory_import_spec.rb

@@ -0,0 +1,30 @@
+# 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 'spec_helper'
+
+describe DeepL::Resources::TranslationMemoryImport do
+  subject(:translation_memory_import) do
+    described_class.new({
+                          'job_id' => '5b1a0a52-1f3b-4b7f-9f6b-9d4d3f5b6c7d',
+                          'upload_url' => 'https://storage.example.com/upload',
+                          'expires_at' => '2026-01-01T00:00:00Z'
+                        }, nil, nil)
+  end
+
+  describe '#initialize' do
+    it 'creates a resource' do
+      expect(translation_memory_import).to be_a(described_class)
+    end
+
+    it 'assigns the attributes' do
+      expect(translation_memory_import.job_id).to eq('5b1a0a52-1f3b-4b7f-9f6b-9d4d3f5b6c7d')
+      expect(translation_memory_import.upload_url).to eq('https://storage.example.com/upload')
+      expect(translation_memory_import.expires_at).to eq(Time.parse('2026-01-01T00:00:00Z'))
+      expect(translation_memory_import.to_s)
+        .to eq('TranslationMemoryImport: ID: 5b1a0a52-1f3b-4b7f-9f6b-9d4d3f5b6c7d')
+    end
+  end
+end

data/spec/resources/translation_memory_job_spec.rb

@@ -0,0 +1,109 @@
+# 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 'spec_helper'
+
+describe DeepL::Resources::TranslationMemoryJob do
+  subject(:job) { described_class.new(response, nil, nil) }
+
+  let(:response) do
+    {
+      'job_id' => '5b1a0a52-1f3b-4b7f-9f6b-9d4d3f5b6c7d',
+      'product' => 'translation_memory',
+      'operation' => 'import',
+      'creation_time' => '2026-01-01T00:00:00Z',
+      'updated_time' => '2026-01-02T00:00:00Z',
+      'source_file' => { 'content_type' => 'application/xml', 'content_length' => 128 },
+      'parameters' => { 'display_name' => 'Legal' },
+      'results' => [
+        { 'status' => 'completed', 'translation_memory_id' => 'tm-1',
+          'skipped_segment_count' => 2 }
+      ]
+    }
+  end
+
+  describe '#initialize' do
+    it 'creates a resource' do
+      expect(job).to be_a(described_class)
+    end
+
+    it 'assigns the job level attributes' do
+      expect(job.job_id).to eq('5b1a0a52-1f3b-4b7f-9f6b-9d4d3f5b6c7d')
+      expect(job.product).to eq('translation_memory')
+      expect(job.operation).to eq('import')
+      expect(job.creation_time).to eq(Time.parse('2026-01-01T00:00:00Z'))
+      expect(job.updated_time).to eq(Time.parse('2026-01-02T00:00:00Z'))
+      expect(job.display_name).to eq('Legal')
+      expect(job.source_content_type).to eq('application/xml')
+      expect(job.source_content_length).to eq(128)
+    end
+
+    it 'maps the single result and delegates the status helpers to it' do
+      expect(job.result).to be_a(DeepL::Resources::TranslationMemoryJobResult)
+      expect(job.status).to eq('completed')
+      expect(job.finished?).to be(true)
+      expect(job.awaiting_input?).to be(false)
+      expect(job.error?).to be(false)
+      expect(job.result.translation_memory_id).to eq('tm-1')
+      expect(job.result.skipped_segment_count).to eq(2)
+    end
+  end
+
+  context 'when the job is awaiting its file upload' do
+    let(:response) do
+      { 'job_id' => 'job-1', 'operation' => 'import',
+        'results' => [{ 'status' => 'awaiting_input',
+                        'status_metadata' => { 'required_action' => 'Waiting for upload' } }] }
+    end
+
+    it 'exposes the required action and does not report the job as finished' do
+      expect(job.awaiting_input?).to be(true)
+      expect(job.finished?).to be(false)
+      expect(job.result.required_action).to eq('Waiting for upload')
+    end
+  end
+
+  context 'when the export job completed' do
+    let(:response) do
+      { 'job_id' => 'job-2', 'operation' => 'export',
+        'parameters' => { 'translation_memory_id' => 'tm-1' },
+        'results' => [{ 'status' => 'completed', 'download_url' => 'https://example.com/tmx',
+                        'expires_at' => '2026-01-03T00:00:00Z' }] }
+    end
+
+    it 'exposes the download URL and its expiry' do
+      expect(job.translation_memory_id).to eq('tm-1')
+      expect(job.result.download_url).to eq('https://example.com/tmx')
+      expect(job.result.expires_at).to eq(Time.parse('2026-01-03T00:00:00Z'))
+      expect(job.to_s).to eq('TranslationMemoryJob: export - ID: job-2 - Status: completed')
+    end
+  end
+
+  context 'when the job failed' do
+    let(:response) do
+      { 'job_id' => 'job-3', 'operation' => 'import',
+        'results' => [{ 'status' => 'failed', 'error' => { 'message' => 'Invalid TMX' } }] }
+    end
+
+    it 'reports the error and treats the job as finished' do
+      expect(job.error?).to be(true)
+      expect(job.finished?).to be(true)
+      expect(job.error_message).to eq('Invalid TMX')
+    end
+  end
+
+  context 'when the API returned no result' do
+    let(:response) { { 'job_id' => 'job-4', 'operation' => 'import' } }
+
+    it 'reports neither a status nor an error' do
+      expect(job.result).to be_nil
+      expect(job.status).to be_nil
+      expect(job.finished?).to be(false)
+      expect(job.awaiting_input?).to be(false)
+      expect(job.error?).to be(false)
+      expect(job.error_message).to be_nil
+    end
+  end
+end

data/spec/resources/translation_memory_segments_spec.rb

@@ -0,0 +1,78 @@
+# 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 'spec_helper'
+
+describe DeepL::Resources::TranslationMemorySegments do
+  subject(:segments_page) { described_class.new(response, nil, nil) }
+
+  let(:response) do
+    {
+      'segments' => [
+        {
+          'source_segment_id' => 'tm-1-source-0',
+          'source_text' => 'Quelltext Nummer 0',
+          'creation_time' => '2026-01-01T00:00:00Z',
+          'updated_time' => '2026-01-02T00:00:00Z',
+          'last_used_time' => '2026-01-03T00:00:00Z',
+          'targets' => [
+            {
+              'target_segment_id' => 'tm-1-target-en-0',
+              'target_language' => 'en',
+              'target_text' => 'Source text number 0',
+              'creation_time' => '2026-01-01T00:00:00Z',
+              'updated_time' => '2026-01-02T00:00:00Z',
+              'last_used_time' => '2026-01-03T00:00:00Z'
+            }
+          ]
+        }
+      ],
+      'segment_count' => 12,
+      'next_page_cursor' => 'NQ'
+    }
+  end
+
+  describe '#initialize' do
+    it 'creates a resource' do
+      expect(segments_page).to be_a(described_class)
+    end
+
+    it 'assigns the page level attributes' do
+      expect(segments_page.segment_count).to eq(12)
+      expect(segments_page.next_page_cursor).to eq('NQ')
+      expect(segments_page.next_page?).to be(true)
+      expect(segments_page.to_s).to eq('1 of 12 segment(s)')
+    end
+
+    it 'maps the segments into resources' do
+      segment = segments_page.segments.first
+      expect(segment).to be_a(DeepL::Resources::TranslationMemorySegment)
+      expect(segment.source_segment_id).to eq('tm-1-source-0')
+      expect(segment.source_text).to eq('Quelltext Nummer 0')
+      expect(segment.creation_time).to eq(Time.parse('2026-01-01T00:00:00Z'))
+      expect(segment.updated_time).to eq(Time.parse('2026-01-02T00:00:00Z'))
+      expect(segment.last_used_time).to eq(Time.parse('2026-01-03T00:00:00Z'))
+    end
+
+    it 'maps the target segments into resources' do
+      target = segments_page.segments.first.targets.first
+      expect(target).to be_a(DeepL::Resources::TranslationMemoryTargetSegment)
+      expect(target.target_segment_id).to eq('tm-1-target-en-0')
+      expect(target.target_language).to eq('en')
+      expect(target.target_text).to eq('Source text number 0')
+      expect(target.to_s).to eq('en: Source text number 0')
+    end
+  end
+
+  context 'when the response is the last page' do
+    let(:response) { { 'segments' => [], 'segment_count' => 12 } }
+
+    it 'reports no further page' do
+      expect(segments_page.segments).to eq([])
+      expect(segments_page.next_page_cursor).to be_nil
+      expect(segments_page.next_page?).to be(false)
+    end
+  end
+end

data/spec/resources/translation_memory_spec.rb

@@ -12,7 +12,9 @@ describe DeepL::Resources::TranslationMemory do
                           'name' => 'Legal',
                           'source_language' => 'en',
                           'target_languages' => %w[es de],
-                          'segment_count' => 3542
+                          'segment_count' => 3542,
+                          'creation_time' => '2026-01-01T00:00:00Z',
+                          'updated_time' => '2026-01-02T00:00:00Z'
                         }, nil, nil)
   end
 
@@ -29,6 +31,21 @@ describe DeepL::Resources::TranslationMemory do
         expect(translation_memory.source_language).to eq('en')
         expect(translation_memory.target_languages).to eq(%w[es de])
         expect(translation_memory.segment_count).to eq(3542)
+        expect(translation_memory.creation_time).to eq(Time.parse('2026-01-01T00:00:00Z'))
+        expect(translation_memory.updated_time).to eq(Time.parse('2026-01-02T00:00:00Z'))
+      end
+    end
+
+    context 'when the optional timestamps are missing' do
+      subject(:translation_memory) do
+        described_class.new({ 'translation_memory_id' => 'tm-1', 'name' => 'Legal' }, nil, nil)
+      end
+
+      it 'leaves the timestamps nil and defaults the collections' do
+        expect(translation_memory.creation_time).to be_nil
+        expect(translation_memory.updated_time).to be_nil
+        expect(translation_memory.target_languages).to eq([])
+        expect(translation_memory.segment_count).to eq(0)
       end
     end
   end

data/spec/spec_helper.rb

@@ -14,59 +14,29 @@ SimpleCov.formatter = SimpleCov::Formatter::CoberturaFormatter
 require_relative '../lib/deepl'
 require_relative 'integration_tests/integration_test_utils'
 
+# Auto-load test helpers under spec/support
+Dir[File.expand_path('support/**/*.rb', __dir__)].sort.each { |f| require f }
+
 # Lib config
 ENV['DEEPL_AUTH_KEY'] ||= 'TEST-TOKEN'
 
-# General helpers
-def build_deepl_api
-  DeepL::API.new(DeepL::Configuration.new)
-end
+RSpec.configure do |config|
+  config.include ManagedGlossary
+  config.include ManagedStyleRule
+  config.include ManagedTranslationMemory
 
-uri_ignoring_deepl_api_subdomain = lambda do |request1, request2|
-  deepl_api_regexp = %r{https?://api.*\.deepl\.com/}
-  uri1 = request1.uri
-  uri2 = request2.uri
-  uri1_match = uri1.match(deepl_api_regexp)
-  uri2_match = uri2.match(deepl_api_regexp)
-  if uri1_match && uri2_match
-    uri1_without_deepl_domain = uri1.gsub(uri1_match[0], '')
-    uri2_without_deepl_domain = uri2.gsub(uri2_match[0], '')
-    uri1_without_deepl_domain == uri2_without_deepl_domain
-  else
-    uri1 == uri2
+  config.before(:each, :mock_server_only) do
+    skip 'Only runs on mock server' unless ENV.key?('DEEPL_MOCK_SERVER_PORT')
   end
-end
-
-headers_ignoring_user_agent = lambda do |request1, request2|
-  user_agent_key = 'User-Agent'
-  # Pass by reference, so we need to use a copy of the headers
-  headers1 = request1.headers.dup
-  headers2 = request2.headers.dup
-  headers1_has_user_agent = headers1.key?(user_agent_key)
-  headers2_has_user_agent = headers2.key?(user_agent_key)
-  return false if headers1_has_user_agent != headers2_has_user_agent
 
-  headers1.delete(user_agent_key)
-  headers2.delete(user_agent_key)
-  headers1 == headers2
+  config.before(:each, :real_server_only) do
+    skip 'Only runs on real server' if ENV.key?('DEEPL_MOCK_SERVER_PORT')
+  end
 end
 
-# VCR tapes configuration
-require 'vcr'
-VCR.configure do |config|
-  config.cassette_library_dir = 'spec/fixtures/vcr_cassettes'
-  config.hook_into :webmock
-  config.filter_sensitive_data('VALID_TOKEN') { ENV.fetch('DEEPL_AUTH_KEY', nil) }
-
-  # to record new or missing VCR cassettes, call rspec like this:
-  # $ VCR_RECORD_MODE=new_episodes bundle exec rspec
-
-  record_mode = ENV['VCR_RECORD_MODE'] ? ENV['VCR_RECORD_MODE'].to_sym : :none
-  config.default_cassette_options = {
-    record: record_mode,
-    match_requests_on: [:method, uri_ignoring_deepl_api_subdomain, :body,
-                        headers_ignoring_user_agent]
-  }
+# General helpers
+def build_deepl_api
+  DeepL::API.new(DeepL::Configuration.new)
 end
 
 # Test helpers

data/spec/support/live_mock_server.rb

@@ -0,0 +1,12 @@
+# 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
+
+# Shared setup for integration specs that hit the live mock server: expose an
+# API the server rejects as unauthorized without mutating global DeepL state.
+RSpec.shared_context 'with a live mock server' do
+  let(:unauthorized_api) do
+    DeepL::API.new(DeepL::Configuration.new(auth_key: 'invalid'))
+  end
+end