deepl-rb 3.9.0 → 3.10.0

data/spec/offline/translation_memories_spec.rb

@@ -0,0 +1,463 @@
+# 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
+
+require_relative 'offline_helper'
+
+describe DeepL::TranslationMemoryApi do
+  let(:memories) { DeepL.translation_memories }
+  let(:upload_url) { 'https://storage.example.test/upload?sig=abc' }
+  let(:download_url) { 'https://storage.example.test/download?sig=def' }
+  let(:memory_json) do
+    { translation_memory_id: 'tm-1', name: 'memory', source_language: 'de',
+      target_languages: %w[en fr], segment_count: 3, creation_time: '2026-01-02T03:04:05Z',
+      updated_time: '2026-02-03T04:05:06Z' }
+  end
+
+  def job_json(status, operation: 'import', **result)
+    { job_id: 'j-1', product: 'translation_memory', operation: operation,
+      results: [{ status: status }.merge(result)] }
+  end
+
+  def job_resource(status, **result)
+    json = job_json(status, operation: 'export', **result).to_json
+    DeepL::Resources::TranslationMemoryJob.new(JSON.parse(json), nil, nil)
+  end
+
+  def stub_job(*replies)
+    stub_request(:get, url('/v3/translation_memories/jobs/j-1')).with(headers: json_headers)
+                                                                .to_return(*replies)
+  end
+
+  def no_authorization
+    ->(request) { !request.headers.key?('Authorization') }
+  end
+
+  describe '#list' do
+    it 'sends a GET without a query by default and parses the timestamps' do
+      stub_request(:get, url('/v3/translation_memories'))
+        .with(headers: json_headers).to_return(reply(translation_memories: [memory_json]))
+
+      memory = memories.list.first
+
+      expect([memory.creation_time, memory.updated_time])
+        .to eq([Time.utc(2026, 1, 2, 3, 4, 5), Time.utc(2026, 2, 3, 4, 5, 6)])
+    end
+
+    it 'sends page and page_size in the query' do
+      stub_request(:get, url('/v3/translation_memories?page=1&page_size=20'))
+        .to_return(reply(translation_memories: []))
+
+      memories.list(page: 1, page_size: 20)
+    end
+
+    it 'does not send an option set to nil' do
+      stub_request(:get, url('/v3/translation_memories?page_size=20'))
+        .to_return(reply(translation_memories: []))
+
+      memories.list(page: nil, page_size: 20)
+    end
+  end
+
+  describe '#find and #destroy' do
+    it 'accept an ID or a translation memory object' do
+      object = DeepL::Resources::TranslationMemory.new({ 'translation_memory_id' => 'tm-1' },
+                                                       nil, nil)
+      stub_request(:get, url('/v3/translation_memories/tm-1'))
+        .with(headers: json_headers).to_return(reply(memory_json))
+      stub_request(:delete, url('/v3/translation_memories/tm-1'))
+        .with(headers: json_headers).to_return(status: 204)
+
+      memories.find('tm-1')
+      memories.find(object)
+
+      expect([memories.destroy('tm-1'), memories.destroy(object)]).to eq(%w[tm-1 tm-1])
+    end
+
+    ['', nil].each do |id|
+      it "raise Error for the ID #{id.inspect} without sending a request" do
+        expect { memories.find(id) }.to raise_error(DeepL::Exceptions::Error, /must not be empty/)
+        expect { memories.destroy(id) }
+          .to raise_error(DeepL::Exceptions::Error, /must not be empty/)
+      end
+    end
+  end
+
+  describe 'IDs in the path' do
+    it 'URL-encodes translation memory and job IDs' do # rubocop:disable RSpec/ExampleLength
+      stub_request(:get, url('/v3/translation_memories/a%2Fb%20c')).to_return(reply(memory_json))
+      stub_request(:delete, url('/v3/translation_memories/a%2Fb%20c')).to_return(status: 204)
+      stub_request(:get, url('/v3/translation_memories/a%2Fb%20c/segments'))
+        .to_return(reply(segment_count: 0, segments: []))
+      stub_request(:post, url('/v3/translation_memories/a%2Fb%20c/export'))
+        .to_return(reply({ job_id: 'j-1' }, 202))
+      stub_request(:get, url('/v3/translation_memories/jobs/j%3F1'))
+        .to_return(reply(job_json('processing')))
+
+      memories.find('a/b c')
+      memories.destroy('a/b c')
+      memories.segments('a/b c')
+      memories.create_export('a/b c')
+      memories.find_job('j?1')
+    end
+  end
+
+  describe 'timestamps' do
+    it 'are read as UTC without an offset and as nil when malformed' do # rubocop:disable RSpec/ExampleLength
+      times = { 'creation_time' => '2026-01-02T03:04:05', 'updated_time' => 'not a time',
+                'last_used_time' => 'not a time', 'expires_at' => '2026-01-02T03:04:05' }
+      job = DeepL::Resources::TranslationMemoryJob.new(times.merge('results' => [times]), nil,
+                                                       nil)
+      parsed = [DeepL::Resources::TranslationMemory.new(times, nil, nil),
+                DeepL::Resources::TranslationMemorySegment.new(times),
+                DeepL::Resources::TranslationMemoryTargetSegment.new(times), job]
+
+      expect(parsed.map { |resource| [resource.creation_time, resource.updated_time] })
+        .to all(eq([Time.utc(2026, 1, 2, 3, 4, 5), nil]))
+      expect([DeepL::Resources::TranslationMemoryImport.new(times, nil, nil).expires_at,
+              job.result.expires_at]).to all(eq(Time.utc(2026, 1, 2, 3, 4, 5)))
+    end
+  end
+
+  describe '#segments' do
+    let(:segments_json) do
+      { segment_count: 7, next_page_cursor: 'c-2',
+        segments: [{ source_segment_id: 'a', source_text: 'Haus',
+                     targets: [{ target_segment_id: 'b', target_language: 'en',
+                                 target_text: 'house', creation_time: '2026-01-02T03:04:05Z' }] }] }
+    end
+
+    it 'sends the paging and filter options in the query' do
+      query = 'page_size=5&page_cursor=c-1&filter_text=a%20b&filter_case_sensitive=true'
+      stub_request(:get, url("/v3/translation_memories/tm-1/segments?#{query}"))
+        .with(headers: json_headers).to_return(reply(segments_json))
+
+      memories.segments('tm-1', page_size: 5, page_cursor: 'c-1', filter_text: 'a b',
+                                filter_case_sensitive: true)
+    end
+
+    it 'does not send an option set to nil' do
+      stub_request(:get, url('/v3/translation_memories/tm-1/segments?page_size=5'))
+        .to_return(reply(segments_json))
+
+      memories.segments('tm-1', page_size: 5, page_cursor: nil, filter_text: nil,
+                                filter_case_sensitive: nil)
+    end
+
+    it 'parses the timestamp of a target and the next page' do
+      stub_request(:get, url('/v3/translation_memories/tm-1/segments'))
+        .to_return(reply(segments_json))
+
+      page = memories.segments('tm-1')
+      segment = page.segments.first
+      target = segment.targets.first
+
+      expect([page.next_page?, target.creation_time]).to eq([true, Time.utc(2026, 1, 2, 3, 4, 5)])
+    end
+
+    it 'reports no next page when there is no cursor' do
+      stub_request(:get, url('/v3/translation_memories/tm-1/segments'))
+        .to_return(reply(segment_count: 0, segments: []))
+
+      expect(memories.segments('tm-1').next_page?).to be(false)
+    end
+  end
+
+  describe '#create_import' do
+    it 'sends the source file description' do
+      stub_request(:post, url('/v3/translation_memories/import'))
+        .with(body: { source_file: { file_name: 'a.tmx', content_length: 12 } },
+              headers: json_headers)
+        .to_return(reply({ job_id: 'j-1', upload_url: upload_url }, 201))
+
+      memories.create_import('a.tmx', 12)
+    end
+
+    it 'sends the content type and display name when given, and parses the expiry' do
+      stub_request(:post, url('/v3/translation_memories/import'))
+        .with(body: { source_file: { file_name: 'a.tmx', content_length: 12,
+                                     content_type: 'application/x-tmx' },
+                      parameters: { display_name: 'My memory' } })
+        .to_return(reply({ job_id: 'j-1', upload_url: upload_url,
+                           expires_at: '2026-03-04T05:06:07Z' }, 201))
+
+      created = memories.create_import('a.tmx', 12, content_type: 'application/x-tmx',
+                                                    display_name: 'My memory')
+
+      expect(created.expires_at).to eq(Time.utc(2026, 3, 4, 5, 6, 7))
+    end
+  end
+
+  describe '#create_import with extra_body_parameters' do
+    it 'adds them to the request body last' do
+      stub_request(:post, url('/v3/translation_memories/import'))
+        .with(body: { source_file: { file_name: 'a.tmx', content_length: 12 },
+                      parameters: { display_name: 'replaced' }, extra: 1 })
+        .to_return(reply({ job_id: 'j-1', upload_url: upload_url }, 201))
+
+      memories.create_import('a.tmx', 12, display_name: 'My memory',
+                                          extra_body_parameters: {
+                                            parameters: { display_name: 'replaced' }, extra: 1
+                                          })
+    end
+  end
+
+  describe '#upload_file' do
+    it 'sends the content as the PUT body without credentials' do
+      stub_request(:put, upload_url)
+        .with(body: Fixtures::EXAMPLE_TMX, headers: { 'Content-Type' => 'application/xml' },
+              &no_authorization).to_return(status: 200)
+
+      memories.upload_file(upload_url, Fixtures::EXAMPLE_TMX)
+    end
+
+    it 'sends the User-Agent of config.headers to the storage URL' do
+      DeepL.configuration.headers = { 'user-agent' => 'mine/1' }
+      stub_request(:put, upload_url).with(headers: { 'User-Agent' => 'mine/1' }, &no_authorization)
+                                    .to_return(status: 200)
+
+      memories.upload_file(upload_url, Fixtures::EXAMPLE_TMX)
+    end
+
+    it 'takes the URL from an import and sends the given content type and bytes' do
+      created = DeepL::Resources::TranslationMemoryImport.new({ 'upload_url' => upload_url },
+                                                              nil, nil)
+      stub_request(:put, upload_url)
+        .with(body: Fixtures::BINARY_CONTENT, headers: { 'Content-Type' => 'text/xml' },
+              &no_authorization).to_return(status: 200)
+
+      memories.upload_file(created, Fixtures::BINARY_CONTENT, content_type: 'text/xml')
+    end
+
+    it 'raises AuthorizationFailed for a storage reply of 403' do
+      stub_request(:put, upload_url).to_return(status: 403, body: 'Request has expired')
+
+      expect { memories.upload_file(upload_url, 'tmx') }
+        .to raise_error(DeepL::Exceptions::AuthorizationFailed)
+    end
+  end
+
+  describe '#find_job' do
+    it 'parses the job parameters, status and result' do
+      stub_job(reply(job_json('completed', translation_memory_id: 'tm-1', skipped_segment_count: 2)
+                       .merge(parameters: { translation_memory_id: 'tm-1',
+                                            display_name: 'memory' })))
+
+      job = memories.find_job('j-1')
+
+      expect([job.status, job.finished?, job.error?, job.translation_memory_id, job.display_name])
+        .to eq(['completed', true, false, 'tm-1', 'memory'])
+    end
+
+    {
+      'awaiting_input' => [false, true, false, false, true],
+      'processing' => [false, false, false, false, true],
+      'completed' => [true, false, false, true, true],
+      'downloaded' => [true, false, false, false, true],
+      'failed' => [true, false, true, false, false],
+      'expired' => [true, false, true, false, false]
+    }.each do |status, flags|
+      it "parses the #{status} status as finished, awaiting input, error, done, ok: " \
+         "#{flags.inspect}" do
+        stub_job(reply(job_json(status)))
+
+        job = memories.find_job('j-1')
+
+        expect([job.finished?, job.awaiting_input?, job.error?, job.done?, job.ok?]).to eq(flags)
+      end
+    end
+
+    it 'rejects an empty job ID without sending a request' do
+      expect { memories.find_job('') }.to raise_error(DeepL::Exceptions::Error, /must not be empty/)
+    end
+  end
+
+  describe '#wait_until_job_done' do
+    it 'returns a finished job without sleeping' do
+      stub = stub_job(reply(job_json('completed')))
+
+      expect(memories.wait_until_job_done('j-1').status).to eq('completed')
+      expect(stub).to have_been_requested.once
+    end
+
+    it 'polls until the job is completed' do
+      stub = stub_job(reply(job_json('awaiting_input')), reply(job_json('completed')))
+
+      job = memories.wait_until_job_done(DeepL::Resources::TranslationMemoryJob.new(
+                                           { 'job_id' => 'j-1' }, nil, nil
+                                         ))
+
+      expect(job.status).to eq('completed')
+      expect(stub).to have_been_requested.twice
+    end
+
+    %w[failed expired].each do |status|
+      it "raises Error with the API message when the job is #{status}" do
+        stub_job(reply(job_json(status, error: { message: 'bad file' })))
+
+        expect { memories.wait_until_job_done('j-1') }
+          .to raise_error(DeepL::Exceptions::Error, /import: bad file/)
+      end
+    end
+
+    it 'raises Error with the status when the job has no error message' do
+      stub_job(reply(job_json('failed')))
+
+      expect do
+        memories.wait_until_job_done('j-1')
+      end.to raise_error(DeepL::Exceptions::Error, /: failed/)
+    end
+
+    it 'raises Error when timeout_s is exceeded while the job is not finished' do
+      stub_job(reply(job_json('processing')))
+
+      expect { memories.wait_until_job_done('j-1', timeout_s: 0) }
+        .to raise_error(DeepL::Exceptions::Error, /timeout of 0s exceeded/)
+    end
+
+    it 'cuts the last sleep to the deadline of timeout_s' do
+      stub_job(reply(job_json('processing')))
+      slept = []
+      allow(memories).to receive(:sleep) do |seconds|
+        slept << seconds
+        Kernel.sleep(seconds)
+      end
+
+      expect { memories.wait_until_job_done('j-1', timeout_s: 0.2) }
+        .to raise_error(DeepL::Exceptions::Error, /timeout of 0.2s exceeded/)
+      expect(slept).to all(be <= 0.2)
+    end
+  end
+
+  describe '#create_export' do
+    it 'sends a POST with an empty body and parses a new export' do
+      stub_request(:post, url('/v3/translation_memories/tm-1/export'))
+        .with(body: '{}', headers: json_headers)
+        .to_return(reply({ job_id: 'j-1', parameters: { translation_memory_id: 'tm-1' } }, 202))
+
+      export = memories.create_export('tm-1')
+
+      expect([export.translation_memory_id, export.reused_existing?]).to eq(['tm-1', false])
+    end
+
+    it 'reports an export that the API reused' do
+      stub_request(:post, url('/v3/translation_memories/tm-1/export'))
+        .to_return(reply({ job_id: 'j-1' }, 200))
+
+      expect(memories.create_export('tm-1').reused_existing?).to be(true)
+    end
+  end
+
+  describe '#download_export' do
+    let(:output) { File.join(temp_dir, 'export.tmx') }
+
+    include_context 'with a temporary directory'
+
+    it 'writes the download to the file byte for byte, without credentials' do
+      stub_request(:get, download_url).with(&no_authorization)
+                                      .to_return(status: 200, body: Fixtures::BINARY_CONTENT)
+
+      memories.download_export(download_url, output)
+
+      expect(File.binread(output)).to eq(Fixtures::BINARY_CONTENT)
+    end
+
+    it 'takes the URL from a finished export job' do
+      stub_request(:get, download_url).to_return(status: 200, body: 'tmx')
+
+      memories.download_export(job_resource('completed', download_url: download_url), output)
+
+      expect(File.read(output)).to eq('tmx')
+    end
+
+    it 'raises Error for a job without a download URL' do
+      expect { memories.download_export(job_resource('processing'), output) }
+        .to raise_error(DeepL::Exceptions::Error, /no download URL/)
+    end
+
+    it 'raises the Errno error when the file cannot be written' do
+      stub_request(:get, download_url).to_return(status: 200, body: 'tmx')
+
+      expect { memories.download_export(download_url, File.join(temp_dir, 'missing', 'x.tmx')) }
+        .to raise_error(Errno::ENOENT)
+    end
+
+    it 'raises AuthorizationFailed for a storage reply of 403' do
+      stub_request(:get, download_url).to_return(status: 403, body: 'Request has expired')
+
+      expect { memories.download_export(download_url, output) }
+        .to raise_error(DeepL::Exceptions::AuthorizationFailed)
+    end
+
+    it 'retries a storage reply of 503 and raises ServerError' do
+      stub = stub_request(:get, download_url).to_return(status: 503)
+
+      expect { memories.download_export(download_url, output) }
+        .to raise_error(DeepL::Exceptions::ServerError)
+      expect(stub).to have_been_requested.times(3)
+    end
+  end
+
+  describe 'convenience methods' do
+    include_context 'with a temporary directory'
+
+    it 'imports a file: creates the import, uploads the bytes and waits for the job' do # rubocop:disable RSpec/ExampleLength
+      path = File.join(temp_dir, 'memory.tmx')
+      File.write(path, Fixtures::EXAMPLE_TMX)
+      stub_request(:post, url('/v3/translation_memories/import'))
+        .with(body: { source_file: { file_name: 'memory.tmx',
+                                     content_length: Fixtures::EXAMPLE_TMX.bytesize },
+                      parameters: { display_name: 'imported' } })
+        .to_return(reply({ job_id: 'j-1', upload_url: upload_url }, 201))
+      stub_request(:put, upload_url).with(body: Fixtures::EXAMPLE_TMX).to_return(status: 200)
+      stub_job(reply(job_json('completed', translation_memory_id: 'tm-1')))
+
+      job = memories.import_from_filepath(path, display_name: 'imported')
+
+      expect(job.finished?).to be(true)
+    end
+
+    it 'imports a file with a content type and extra body parameters' do # rubocop:disable RSpec/ExampleLength
+      path = File.join(temp_dir, 'memory.tmx')
+      File.write(path, Fixtures::EXAMPLE_TMX)
+      stub_request(:post, url('/v3/translation_memories/import'))
+        .with(body: { source_file: { file_name: 'memory.tmx',
+                                     content_length: Fixtures::EXAMPLE_TMX.bytesize,
+                                     content_type: 'text/xml' }, extra: 'x' })
+        .to_return(reply({ job_id: 'j-1', upload_url: upload_url }, 201))
+      stub_request(:put, upload_url).with(headers: { 'Content-Type' => 'text/xml' })
+                                    .to_return(status: 200)
+      stub_job(reply(job_json('completed')))
+
+      memories.import_from_filepath(path, content_type: 'text/xml',
+                                          extra_body_parameters: { extra: 'x' })
+    end
+
+    it 'raises Error for a missing import file without sending a request' do
+      expect { memories.import_from_filepath(File.join(temp_dir, 'missing.tmx')) }
+        .to raise_error(DeepL::Exceptions::Error, /No file found/)
+    end
+
+    it 'raises the Errno error for an unreadable import file without sending a request' do
+      expect { memories.import_from_filepath(temp_dir) }.to raise_error(Errno::EISDIR)
+    end
+
+    it 'raises Errno::ENOENT for a missing output directory before creating the export job' do
+      expect { memories.export_to_filepath('tm-1', File.join(temp_dir, 'missing', 'x.tmx')) }
+        .to raise_error(Errno::ENOENT, /missing/)
+    end
+
+    it 'exports to a file: creates the export, waits for the job and downloads the result' do
+      output = File.join(temp_dir, 'export.tmx')
+      stub_request(:post, url('/v3/translation_memories/tm-1/export'))
+        .to_return(reply({ job_id: 'j-1' }, 202))
+      stub_job(reply(job_json('completed', operation: 'export', download_url: download_url)))
+      stub_request(:get, download_url).to_return(status: 200, body: 'tmx')
+
+      job = memories.export_to_filepath('tm-1', output)
+
+      expect([File.read(output), job.status]).to eq(%w[tmx completed])
+    end
+  end
+end

data/spec/offline/usage_spec.rb

@@ -0,0 +1,151 @@
+# 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
+
+require_relative 'offline_helper'
+
+describe 'usage' do
+  describe 'DeepL.usage' do
+    it 'sends a GET without a body or Content-Type' do
+      stub_request(:get, url('/v2/usage')).with(headers: auth_headers) { bodyless?(_1) }
+                                          .to_return(usage_reply)
+      DeepL.usage
+    end
+
+    it 'reports no exceeded quota while the count is below the limit' do
+      stub_request(:get, url('/v2/usage'))
+        .to_return(reply(character_count: 42, character_limit: 100))
+
+      expect(DeepL.usage.quota_exceeded?).to be(false)
+    end
+
+    it 'reports an exceeded quota when the count reaches the limit' do
+      stub_request(:get,
+                   url('/v2/usage')).to_return(reply(character_count: 100, character_limit: 100))
+
+      expect(DeepL.usage.quota_exceeded?).to be(true)
+    end
+
+    context 'with an API Pro response' do
+      let(:pro_body) do
+        {
+          character_count: 5_947_223, character_limit: 1_000_000_000_000,
+          products: [
+            { product_type: 'write', billing_unit: 'characters', api_key_unit_count: 0,
+              account_unit_count: 5643, api_key_character_count: 0, character_count: 5643 },
+            { product_type: 'translate', billing_unit: 'characters', api_key_unit_count: 636,
+              account_unit_count: 5_941_580, api_key_character_count: 636,
+              character_count: 5_941_580 },
+            { product_type: 'speechToText', billing_unit: 'minutes', api_key_unit_count: 30,
+              account_unit_count: 30, api_key_character_count: 0, character_count: 0 },
+            { product_type: 'speechToSpeech', billing_unit: 'minutes', api_key_unit_count: 12,
+              account_unit_count: 12, api_key_character_count: 0, character_count: 0 }
+          ],
+          api_key_character_count: 636, api_key_character_limit: 1_000_000_000_000,
+          speech_to_text_milliseconds_count: 0, speech_to_text_milliseconds_limit: 0,
+          speech_to_text_minutes_count: 30, speech_to_text_minutes_limit: 600,
+          speech_to_speech_minutes_count: 12, speech_to_speech_minutes_limit: 600,
+          start_time: '2025-05-13T09:18:42Z', end_time: '2025-06-13T09:18:42Z'
+        }
+      end
+
+      before { stub_request(:get, url('/v2/usage')).to_return(reply(pro_body)) }
+
+      it 'parses the per-key, speech and billing period fields' do
+        usage = DeepL.usage
+
+        expect(usage).to have_attributes(
+          character_count: 5_947_223, character_limit: 1_000_000_000_000,
+          start_time: Time.utc(2025, 5, 13, 9, 18, 42), end_time: Time.utc(2025, 6, 13, 9, 18, 42),
+          to_s: '5947223 / 1000000000000'
+        )
+        expect(usage.character).to have_attributes(count: 5_947_223, limit: 1_000_000_000_000)
+        expect(usage.api_key_character).to have_attributes(count: 636, limit: 1_000_000_000_000)
+        expect([usage.speech_to_text_minutes, usage.speech_to_speech_minutes].map(&:to_s))
+          .to eq(['30 of 600', '12 of 600'])
+      end
+
+      it 'parses the per-product usage' do
+        products = DeepL.usage.products
+
+        expect(products).to all(be_a(DeepL::Resources::UsageProduct))
+        expect(products.map(&:product_type)).to eq(%w[write translate speechToText speechToSpeech])
+        expect(products.map(&:billing_unit)).to eq(%w[characters characters minutes minutes])
+        expect(products.map(&:api_key_unit_count)).to eq([0, 636, 30, 12])
+        expect(products.map(&:account_unit_count)).to eq([5643, 5_941_580, 30, 12])
+      end
+    end
+
+    it 'leaves the API Pro fields nil for a Free response' do
+      stub_request(:get, url('/v2/usage')).to_return(reply(character_count: 180_118,
+                                                           character_limit: 1_250_000))
+      usage = DeepL.usage
+
+      expect(usage.character).to have_attributes(count: 180_118, limit: 1_250_000)
+      expect(usage.to_s).to eq('180118 / 1250000')
+      expect(usage.quota_exceeded?).to be(false)
+      DeepL::Resources::Usage::KEYWORD_FIELDS.each do |field|
+        expect(usage.public_send(field)).to be_nil
+      end
+    end
+
+    it 'parses the document and team document usage' do
+      stub_request(:get, url('/v2/usage')).to_return(
+        reply(character_count: 1, character_limit: 100, document_count: 5, document_limit: 5,
+              team_document_count: 2, team_document_limit: 10)
+      )
+      usage = DeepL.usage
+
+      expect(usage.document).to have_attributes(count: 5, limit: 5, limit_reached?: true)
+      expect(usage.team_document).to have_attributes(count: 2, limit: 10, limit_reached?: false)
+      expect(usage.any_limit_reached?).to be(true)
+    end
+
+    it 'does not count the API Pro usage types in any_limit_reached?' do
+      stub_request(:get, url('/v2/usage')).to_return(
+        reply(character_count: 1, character_limit: 100, api_key_character_count: 50,
+              api_key_character_limit: 50)
+      )
+      usage = DeepL.usage
+
+      expect(usage.api_key_character.limit_reached?).to be(true)
+      expect(usage.any_limit_reached?).to be(false)
+    end
+
+    it 'ignores an unparseable billing period and malformed products' do
+      stub_request(:get, url('/v2/usage')).to_return(
+        reply(character_count: 20, character_limit: 500_000, start_time: 'not a timestamp',
+              end_time: '', products: [{ product_type: 'translate' }, 'not an object'])
+      )
+      usage = DeepL.usage
+
+      expect(usage.character_count).to eq(20)
+      expect([usage.start_time, usage.end_time]).to eq([nil, nil])
+      expect(usage.products.map(&:product_type)).to eq(['translate'])
+    end
+
+    it 'keeps the positional constructor working' do
+      usage = DeepL::Resources::Usage.new(1, 10, nil, nil)
+
+      expect([usage.character_count, usage.character_limit, usage.products]).to eq([1, 10, nil])
+    end
+  end
+
+  describe DeepL::Client do
+    let(:client) { described_class.new('client-key', server_url: 'https://client.example.test') }
+
+    it '#get_usage sends GET /v2/usage and parses the usage' do
+      stub_request(:get, 'https://client.example.test/v2/usage')
+        .with(headers: { 'Authorization' => 'DeepL-Auth-Key client-key' })
+        .to_return(reply(character_count: 42, character_limit: 100, document_count: 5,
+                         document_limit: 5))
+
+      usage = client.get_usage
+
+      expect(usage.character).to have_attributes(count: 42, limit: 100, limit_reached?: false)
+      expect(usage.document).to have_attributes(count: 5, limit: 5)
+      expect([usage.any_limit_reached?, usage.team_document]).to eq([true, nil])
+    end
+  end
+end