deepl-rb 2.5.3 → 3.0.1

data/spec/fixtures/vcr_cassettes/usage.yml

@@ -14,7 +14,7 @@ http_interactions:
       Accept:
       - "*/*"
       User-Agent:
-      - Ruby
+      - deepl-ruby/2.5.3 (darwin23) ruby/3.3.3
   response:
     status:
       code: 200
@@ -36,4 +36,136 @@ http_interactions:
       encoding: UTF-8
       string: '{"character_count":353,"character_limit":500000}'
   recorded_at: Mon, 17 May 2021 14:18:32 GMT
-recorded_with: VCR 6.0.0
+- request:
+    method: get
+    uri: https://api-free.deepl.com/v2/usage
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      Authorization:
+      - DeepL-Auth-Key VALID_TOKEN
+      User-Agent:
+      - deepl-ruby/2.5.3(darwin23) ruby/3.3.3
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Accept:
+      - "*/*"
+  response:
+    status:
+      code: 403
+      message: Forbidden
+    headers:
+      Date:
+      - Tue, 02 Jul 2024 13:54:07 GMT
+      Content-Type:
+      - application/json
+      Transfer-Encoding:
+      - chunked
+      Vary:
+      - Accept-Encoding
+      Access-Control-Allow-Origin:
+      - "*"
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains; preload
+      Server-Timing:
+      - l7_lb_tls;dur=101, l7_lb_idle;dur=0, l7_lb_receive;dur=0, l7_lb_total;dur=103
+      Access-Control-Expose-Headers:
+      - Server-Timing, X-Trace-ID
+      X-Trace-Id:
+      - 4dcf2a36b3f14ba89f107449f4b14919
+    body:
+      encoding: ASCII-8BIT
+      string: '{"message":"Wrong endpoint. Use https://api.deepl.com"}'
+  recorded_at: Tue, 02 Jul 2024 13:54:07 GMT
+- request:
+    method: get
+    uri: https://api.deepl.com/v2/usage
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      Authorization:
+      - DeepL-Auth-Key VALID_TOKEN
+      User-Agent:
+      - deepl-ruby/2.5.3 (darwin23) ruby/3.3.3
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Accept:
+      - "*/*"
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Date:
+      - Tue, 02 Jul 2024 14:52:05 GMT
+      Content-Type:
+      - application/json
+      Transfer-Encoding:
+      - chunked
+      Vary:
+      - Accept-Encoding
+      Access-Control-Allow-Origin:
+      - "*"
+      X-Cache-Status:
+      - MISS
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains; preload
+      Server-Timing:
+      - l7_lb_tls;dur=112, l7_lb_idle;dur=1, l7_lb_receive;dur=0, l7_lb_total;dur=115
+      Access-Control-Expose-Headers:
+      - Server-Timing, X-Trace-ID
+      X-Trace-Id:
+      - de53f558d38c43748bf83b27f4f0edc9
+    body:
+      encoding: ASCII-8BIT
+      string: '{"character_count":18593,"character_limit":1000000000000}'
+  recorded_at: Tue, 02 Jul 2024 14:52:05 GMT
+- request:
+    method: get
+    uri: https://api.deepl.com/v2/usage
+    body:
+      encoding: UTF-8
+      string: "{}"
+    headers:
+      Authorization:
+      - DeepL-Auth-Key VALID_TOKEN
+      User-Agent:
+      - deepl-ruby/2.5.3 (darwin23) ruby/3.3.3
+      Content-Type:
+      - application/json
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Accept:
+      - "*/*"
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Date:
+      - Tue, 09 Jul 2024 01:35:37 GMT
+      Content-Type:
+      - application/json
+      Transfer-Encoding:
+      - chunked
+      Vary:
+      - Accept-Encoding
+      Access-Control-Allow-Origin:
+      - "*"
+      X-Cache-Status:
+      - MISS
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains; preload
+      Server-Timing:
+      - l7_lb_tls;dur=137, l7_lb_idle;dur=1, l7_lb_receive;dur=0, l7_lb_total;dur=140
+      Access-Control-Expose-Headers:
+      - Server-Timing, X-Trace-ID
+      X-Trace-Id:
+      - 543309f656244684bb59d30e9dc824b5
+    body:
+      encoding: ASCII-8BIT
+      string: '{"character_count":69328,"character_limit":1000000000000}'
+  recorded_at: Tue, 09 Jul 2024 01:35:37 GMT
+recorded_with: VCR 6.2.0

data/spec/integration_tests/document_api_spec.rb

@@ -0,0 +1,155 @@
+# Copyright 2024 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
+
+require 'spec_helper'
+
+describe DeepL::DocumentApi do
+  before do
+    VCR.turn_off!
+    WebMock.allow_net_connect!
+  end
+
+  after do
+    VCR.turn_on!
+    WebMock.disable_net_connect!
+  end
+
+  default_lang_args = { source_lang: 'EN', target_lang: 'DE' }
+  include_context 'with temp dir'
+
+  describe '#translate_document' do
+    it 'Translates a document from a filepath' do
+      File.unlink(output_document_path)
+      source_lang = default_lang_args[:source_lang]
+      target_lang = default_lang_args[:target_lang]
+      example_doc_path = example_document_path(source_lang)
+      DeepL.document.translate_document(example_doc_path, output_document_path,
+                                        source_lang, target_lang, File.basename(example_doc_path),
+                                        {})
+      output_file_contents = File.read(output_document_path)
+
+      expect(example_document_translation(target_lang)).to eq(output_file_contents)
+    end
+
+    it 'Translates a document from a filepath without a filename' do
+      File.unlink(output_document_path)
+      source_lang = default_lang_args[:source_lang]
+      target_lang = default_lang_args[:target_lang]
+      example_doc_path = example_document_path(source_lang)
+      DeepL.document.translate_document(example_doc_path, output_document_path,
+                                        source_lang, target_lang)
+      output_file_contents = File.read(output_document_path)
+
+      expect(example_document_translation(target_lang)).to eq(output_file_contents)
+    end
+
+    it 'Translates a document using the lower-level methods and returns the correct status' do # rubocop:disable RSpec/ExampleLength
+      File.unlink(output_document_path)
+      source_lang = default_lang_args[:source_lang]
+      target_lang = default_lang_args[:target_lang]
+      example_doc_path = example_document_path(source_lang)
+
+      handle = DeepL.document.upload(example_doc_path, source_lang, target_lang,
+                                     File.basename(example_doc_path), {})
+      doc_status = handle.wait_until_document_translation_finished
+      DeepL.document.download(handle, output_document_path) if doc_status.status != 'error'
+      output_file_contents = File.read(output_document_path)
+
+      expect(example_document_translation(target_lang)).to eq(output_file_contents)
+      expect(doc_status.billed_characters).to eq(example_document_translation(source_lang).length)
+      expect(doc_status.status).to eq('done')
+    end
+
+    it 'Translates a document after retrying the upload once' do # rubocop:disable RSpec/ExampleLength
+      skip 'Only runs on mock server' if real_server?
+      File.unlink(output_document_path)
+      source_lang = default_lang_args[:source_lang]
+      target_lang = default_lang_args[:target_lang]
+      example_doc_path = example_document_path(source_lang)
+      doc_status = nil
+      DeepL.with_session(DeepL::HTTPClientOptions.new({}, nil, enable_ssl_verification: false,
+                                                               read_timeout: 1.0)) do |_session|
+        handle = DeepL.document.upload(example_doc_path, source_lang, target_lang,
+                                       File.basename(example_doc_path), {}, no_response_header(1))
+        doc_status = handle.wait_until_document_translation_finished
+        DeepL.document.download(handle, output_document_path) if doc_status.status != 'error'
+      end
+      output_file_contents = File.read(output_document_path)
+
+      expect(output_file_contents).to eq(example_document_translation(target_lang))
+      expect(doc_status.billed_characters).to eq(example_document_translation(source_lang).length)
+      expect(doc_status.status).to eq('done')
+    end
+  end
+
+  it 'Translates a document after waiting' do # rubocop:disable RSpec/ExampleLength
+    skip 'Only runs on mock server' if real_server?
+    File.unlink(output_document_path)
+    source_lang = default_lang_args[:source_lang]
+    target_lang = default_lang_args[:target_lang]
+    example_doc_path = example_document_path(source_lang)
+    doc_status = nil
+    DeepL.with_session(DeepL::HTTPClientOptions.new({}, nil,
+                                                    enable_ssl_verification: false)) do |_session|
+      handle = DeepL.document.upload(example_doc_path, source_lang, target_lang,
+                                     File.basename(example_doc_path), {},
+                                     doc_translation_queue_time_header(2000).merge(doc_translation_translation_time_header(2000))) # rubocop:disable Layout/LineLength
+      doc_status = handle.wait_until_document_translation_finished
+      DeepL.document.download(handle, output_document_path) if doc_status.status != 'error'
+    end
+    output_file_contents = File.read(output_document_path)
+
+    expect(output_file_contents).to eq(example_document_translation(target_lang))
+    expect(doc_status.billed_characters).to eq(example_document_translation(source_lang).length)
+    expect(doc_status.status).to eq('done')
+  end
+
+  it 'Translates a large document' do # rubocop:disable RSpec/ExampleLength
+    skip 'Only runs on mock server' if real_server?
+    File.unlink(output_document_path)
+    source_lang = default_lang_args[:source_lang]
+    target_lang = default_lang_args[:target_lang]
+    example_doc_path = example_large_document_path(source_lang)
+    doc_status = nil
+    DeepL.with_session(DeepL::HTTPClientOptions.new({}, nil,
+                                                    enable_ssl_verification: false)) do |_session|
+      handle = DeepL.document.upload(example_doc_path, source_lang, target_lang,
+                                     File.basename(example_doc_path), {})
+      doc_status = handle.wait_until_document_translation_finished
+      DeepL.document.download(handle, output_document_path) if doc_status.status != 'error'
+    end
+    output_file_contents = File.read(output_document_path)
+
+    expect(output_file_contents).to eq(example_large_document_translation(target_lang))
+    expect(doc_status.billed_characters).to eq(
+      example_large_document_translation(source_lang).length
+    )
+    expect(doc_status.status).to eq('done')
+  end
+
+  it 'Translates a document with formality set' do # rubocop:disable RSpec/ExampleLength
+    skip 'Only runs on mock server' if real_server?
+    File.unlink(output_document_path)
+    source_lang = default_lang_args[:source_lang]
+    target_lang = default_lang_args[:target_lang]
+    example_doc_path = example_large_document_path(source_lang)
+    doc_status = nil
+    DeepL.with_session(DeepL::HTTPClientOptions.new({}, nil,
+                                                    enable_ssl_verification: false)) do |_session|
+      handle = DeepL.document.upload(example_doc_path, source_lang, target_lang,
+                                     File.basename(example_doc_path),
+                                     { 'formality' => 'prefer_more' })
+      doc_status = handle.wait_until_document_translation_finished
+      DeepL.document.download(handle, output_document_path) if doc_status.status != 'error'
+    end
+    output_file_contents = File.read(output_document_path)
+
+    expect(output_file_contents).to eq(example_large_document_translation(target_lang))
+    expect(doc_status.billed_characters).to eq(
+      example_large_document_translation(source_lang).length
+    )
+    expect(doc_status.status).to eq('done')
+  end
+end

data/spec/integration_tests/integration_test_utils.rb

@@ -0,0 +1,170 @@
+# Copyright 2024 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
+
+require 'securerandom'
+require 'tempfile'
+
+module IntegrationTestUtils # rubocop:disable Metrics/ModuleLength
+  EXAMPLE_TEXT = {
+    'BG' => 'протонен лъч',
+    'CS' => 'protonový paprsek',
+    'DA' => 'protonstråle',
+    'DE' => 'Protonenstrahl',
+    'EL' => 'δέσμη πρωτονίων',
+    'EN' => 'proton beam',
+    'EN-US' => 'proton beam',
+    'EN-GB' => 'proton beam',
+    'ES' => 'haz de protones',
+    'ET' => 'prootonikiirgus',
+    'FI' => 'protonisäde',
+    'FR' => 'faisceau de protons',
+    'HU' => 'protonnyaláb',
+    'ID' => 'berkas proton',
+    'IT' => 'fascio di protoni',
+    'JA' => '陽子ビーム',
+    'KO' => '양성자 빔',
+    'LT' => 'protonų spindulys',
+    'LV' => 'protonu staru kūlis',
+    'NB' => 'protonstråle',
+    'NL' => 'protonenbundel',
+    'PL' => 'wiązka protonów',
+    'PT' => 'feixe de prótons',
+    'PT-BR' => 'feixe de prótons',
+    'PT-PT' => 'feixe de prótons',
+    'RO' => 'fascicul de protoni',
+    'RU' => 'протонный луч',
+    'SK' => 'protónový lúč',
+    'SL' => 'protonski žarek',
+    'SV' => 'protonstråle',
+    'TR' => 'proton ışını',
+    'UK' => 'протонний пучок',
+    'ZH' => '质子束'
+  }.freeze
+
+  def mock_server?
+    ENV.key?('DEEPL_MOCK_SERVER_PORT')
+  end
+
+  def mock_proxy_server?
+    ENV.key?('DEEPL_MOCK_PROXY_SERVER_PORT')
+  end
+
+  def real_server?
+    !mock_server?
+  end
+
+  def setup
+    @input_file = nil
+    @input_file_extension = nil
+    @output_file = nil
+    DeepL.configure do |config|
+      config.auth_key = 'your-api-token'
+    end
+  end
+
+  def teardown
+    unless @input_file.nil?
+      @input_file.close
+      @input_file.unlink
+    end
+    return if @output_file.nil?
+
+    @output_file.close
+    @output_file.unlink
+  end
+
+  def example_document_path(document_language)
+    setup_example_document(EXAMPLE_TEXT[document_language])
+  end
+
+  def example_large_document_path(document_language)
+    setup_example_document("#{EXAMPLE_TEXT[document_language]}\n" * 1000)
+  end
+
+  def setup_example_document(file_content)
+    @input_file_base_name = 'example_input_document' if @input_file_base_name.nil?
+    @input_file_extension = '.txt' if @input_file_extension.nil?
+    if @input_file.nil?
+      @input_file = Tempfile.new([@input_file_base_name, @input_file_extension])
+      @input_file.write(file_content)
+      @input_file.close
+    end
+    @input_file.path
+  end
+
+  def example_document_translation(document_language)
+    EXAMPLE_TEXT[document_language]
+  end
+
+  def example_large_document_translation(document_language)
+    "#{EXAMPLE_TEXT[document_language]}\n" * 1000
+  end
+
+  def output_document_path
+    @output_file = Tempfile.new('example_output_document') if @output_file.nil?
+    @output_file.path
+  end
+
+  # For detailed explanations of these header, check the deepl-mock README.md
+  def no_response_header(no_response_count)
+    { 'mock-server-session-no-response-count' => no_response_count.to_s,
+      'mock-server-session' => SecureRandom.uuid }
+  end
+
+  def respond_with_429_header(response_count)
+    { 'mock-server-session-429-count' => response_count.to_s,
+      'mock-server-session' => SecureRandom.uuid }
+  end
+
+  def set_character_limit_header(response_count) # rubocop:disable Naming/AccessorMethodName
+    { 'mock-server-session-init-character-limit' => response_count.to_s,
+      'mock-server-session' => SecureRandom.uuid }
+  end
+
+  def set_document_limit_header(response_count) # rubocop:disable Naming/AccessorMethodName
+    { 'mock-server-session-init-document-limit' => response_count.to_s,
+      'mock-server-session' => SecureRandom.uuid }
+  end
+
+  def set_team_document_limit_header(response_count) # rubocop:disable Naming/AccessorMethodName
+    { 'mock-server-session-init-team-document-limit' => response_count.to_s,
+      'mock-server-session' => SecureRandom.uuid }
+  end
+
+  def fail_docs_header(response_count)
+    { 'mock-server-session-doc-failure' => response_count.to_s,
+      'mock-server-session' => SecureRandom.uuid }
+  end
+
+  def doc_translation_queue_time_header(response_count)
+    { 'mock-server-session-doc-queue-time' => response_count.to_s,
+      'mock-server-session' => SecureRandom.uuid }
+  end
+
+  def doc_translation_translation_time_header(response_count)
+    { 'mock-server-session-doc-translate-time' => response_count.to_s,
+      'mock-server-session' => SecureRandom.uuid }
+  end
+
+  def expect_proxy_header(response_count)
+    { 'mock-server-session-expect-proxy' => response_count.to_s,
+      'mock-server-session' => SecureRandom.uuid }
+  end
+end
+
+shared_context 'with temp dir' do
+  around do |example|
+    Dir.mktmpdir('deepl-rspec-') do |dir|
+      @temp_dir = dir
+      example.run
+    end
+  end
+
+  attr_reader :temp_dir, :input_file_base_name, :input_file_extension
+end
+
+RSpec.configure do |c|
+  c.include IntegrationTestUtils
+end

data/spec/requests/glossary/create_spec.rb

@@ -1,8 +1,21 @@
+# Copyright 2022 Daniel Herzog
+# 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::Glossary::Create do
+  subject(:create) do
+    described_class.new(api, name, source_lang, target_lang, entries, options)
+  end
+
+  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(:name) { 'Mi Glosario' }
   let(:source_lang) { 'EN' }
@@ -15,19 +28,16 @@ describe DeepL::Requests::Glossary::Create do
   end
   let(:entries_format) { 'tsv' }
   let(:options) { {} }
-  subject do
-    DeepL::Requests::Glossary::Create.new(api, name, source_lang, target_lang, entries, options)
-  end
 
   describe '#initialize' do
-    context 'When building a request' do
-      it 'should create a request object' do
-        expect(subject).to be_a(described_class)
+    context 'when building a request' do
+      it 'creates a request object' do
+        expect(create).to be_a(described_class)
       end
 
-      it 'should set the default value for the entries format if not specified' do
-        request = DeepL::Requests::Glossary::Create.new(api, name, source_lang, target_lang,
-                                                        entries, options)
+      it 'sets the default value for the entries format if not specified' do
+        request = described_class.new(api, name, source_lang, target_lang,
+                                      entries, options)
         expect(request.entries_format).to eq('tsv')
       end
     end
@@ -38,11 +48,11 @@ describe DeepL::Requests::Glossary::Create do
       VCR.use_cassette('glossaries') { example.call }
     end
 
-    context 'When performing a valid request with two glossary entries' do
-      it 'should return a glossaries object' do
-        glossary = subject.request
+    context 'when performing a valid request with two glossary entries' do
+      it 'returns a glossaries object' do
+        glossary = create.request
         expect(glossary).to be_a(DeepL::Resources::Glossary)
-        expect(glossary.id).to be_kind_of(String)
+        expect(glossary.id).to be_a(String)
         expect(glossary.name).to eq('Mi Glosario')
         expect(glossary.ready).to be(true).or be(false)
         expect(glossary.source_lang).to eq('en')

data/spec/requests/glossary/destroy_spec.rb

@@ -1,16 +1,26 @@
+# Copyright 2022 Daniel Herzog
+# 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::Glossary::Destroy do
+  subject(:destroy) { described_class.new(api, id) }
+
+  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) { '367eef44-b533-4d95-be19-74950c7760e9' }
-  subject { DeepL::Requests::Glossary::Destroy.new(api, id) }
+  let(:id) { '9ab5dac2-b7b2-4b4a-808a-e8e305df5ecb' }
 
   describe '#initialize' do
-    context 'When building a request' do
-      it 'should create a request object' do
-        expect(subject).to be_a(described_class)
+    context 'when building a request' do
+      it 'creates a request object' do
+        expect(destroy).to be_a(described_class)
       end
     end
   end
@@ -20,30 +30,36 @@ describe DeepL::Requests::Glossary::Destroy do
       VCR.use_cassette('glossaries') { example.call }
     end
 
-    context 'When performing a valid request' do
+    context 'when performing a valid request' do
+      subject(:destroy) { described_class.new(api, new_glossary.id) }
+
       let(:new_glossary) do
         DeepL::Requests::Glossary::Create.new(api, 'fixture', 'EN', 'ES', [%w[Hello Hola]]).request
       end
-      subject { DeepL::Requests::Glossary::Destroy.new(api, new_glossary.id) }
-      it 'should return an empty object' do
-        response = subject.request
+
+      it 'returns an empty object' do
+        response = destroy.request
         expect(response).to eq(new_glossary.id)
       end
     end
 
-    context 'When deleting a non existing glossary with a valid id' do
+    context 'when deleting a non existing glossary with a valid id' do
+      subject(:destroy) { described_class.new(api, id) }
+
       let(:id) { '00000000-0000-0000-0000-000000000000' }
-      subject { DeepL::Requests::Glossary::Destroy.new(api, id) }
-      it 'should raise a not found error' do
-        expect { subject.request }.to raise_error(DeepL::Exceptions::NotFound)
+
+      it 'raises a not found error' do
+        expect { destroy.request }.to raise_error(DeepL::Exceptions::NotFound)
       end
     end
 
-    context 'When deleting a non existing glossary with an invalid id' do
+    context 'when deleting a non existing glossary with an invalid id' do
+      subject(:destroy) { described_class.new(api, id) }
+
       let(:id) { 'invalid-uuid' }
-      subject { DeepL::Requests::Glossary::Destroy.new(api, id) }
-      it 'should raise a bad request error' do
-        expect { subject.request }.to raise_error(DeepL::Exceptions::BadRequest)
+
+      it 'raises a bad request error' do
+        expect { destroy.request }.to raise_error(DeepL::Exceptions::BadRequest)
       end
     end
   end