deepl-rb 3.9.0 → 3.10.0

data/spec/offline/spoken_terms_spec.rb

@@ -0,0 +1,215 @@
+# 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'
+
+# The client has its own key and server, different from the module configuration, so a request
+# that falls back to module state hits no stub.
+describe 'DeepL::Client spoken terms' do
+  let(:client) { DeepL::Client.new('client-key', server_url: 'https://client.example.test') }
+  let(:collection_json) do
+    { spoken_terms_id: 'st-1', name: 'terms', creation_time: '2026-10-23T17:15:53.434769Z',
+      term_lists: [{ lang: 'en', entry_count: 2 }] }
+  end
+
+  def url(path)
+    "https://client.example.test#{path}"
+  end
+
+  def json_headers
+    { 'Authorization' => 'DeepL-Auth-Key client-key', 'Content-Type' => 'application/json' }
+  end
+
+  def no_body
+    ->(body) { body.to_s.empty? }
+  end
+
+  def collection(json = collection_json)
+    stub_request(:get, url('/v3/spoken-terms/st-1')).to_return(reply(json))
+    client.get_spoken_terms('st-1')
+  end
+
+  describe '#create_spoken_terms' do
+    it 'sends the entries of each language joined by newlines' do
+      stub_request(:post, url('/v3/spoken-terms')).with(
+        body: { name: 'terms', term_lists: [{ lang: 'en', entries: "a\nb" }] },
+        headers: json_headers
+      ).to_return(reply(collection_json, 201))
+
+      client.create_spoken_terms('terms', [DeepL::Resources::SpokenTermsEntries.new('en', %w[a b])])
+    end
+
+    it 'accepts term lists given as hashes and sends the extra body parameters' do
+      stub_request(:post, url('/v3/spoken-terms'))
+        .with(body: { name: 'terms', term_lists: [{ lang: 'de', entries: 'x' }], beta: true })
+        .to_return(reply(collection_json, 201))
+
+      client.create_spoken_terms('terms', [{ lang: 'de', entries: ['x'] }],
+                                 extra_body_parameters: { beta: true })
+    end
+
+    it 'parses the collection, including a creation time with microseconds' do
+      stub_request(:post, url('/v3/spoken-terms')).to_return(reply(collection_json, 201))
+
+      created = client.create_spoken_terms('terms', [])
+
+      expect(created.spoken_terms_id).to eq('st-1')
+      expect(created.creation_time)
+        .to eq(Time.utc(2026, 10, 23, 17, 15, Rational(53_434_769, 1_000_000)))
+      expect(created.term_lists.map { |l| [l.lang, l.entry_count] }).to eq([['en', 2]])
+    end
+  end
+
+  describe 'SpokenTerms#creation_time' do
+    it 'is nil for a malformed timestamp' do
+      expect(collection(collection_json.merge(creation_time: 'yesterday')).creation_time).to be_nil
+    end
+
+    it 'reads a timestamp without an offset as UTC, not local time' do
+      original_tz = ENV.fetch('TZ', nil)
+      ENV['TZ'] = 'America/New_York'
+      expect(collection(collection_json.merge(creation_time: '2026-10-23T17:15:53')).creation_time)
+        .to eq(Time.utc(2026, 10, 23, 17, 15, 53))
+    ensure
+      ENV['TZ'] = original_tz
+    end
+  end
+
+  describe 'term check' do
+    it 'strips surrounding whitespace from each term before sending it' do
+      stub_request(:post, url('/v3/spoken-terms'))
+        .with(body: { name: 'terms', term_lists: [{ lang: 'en', entries: "API\nDeepL" }] })
+        .to_return(reply(collection_json, 201))
+
+      client.create_spoken_terms('terms', [{ lang: 'en', entries: [' API ', "DeepL\n"] }])
+    end
+
+    [["a\nb"], ['  ']].each do |bad|
+      it "raises ValidationError for #{bad.inspect} and sends no request" do
+        expect { client.create_spoken_terms('terms', [{ lang: 'en', entries: bad }]) }
+          .to raise_error(DeepL::Exceptions::ValidationError)
+        expect { client.update_spoken_terms('st-1', term_lists: [{ lang: 'en', entries: bad }]) }
+          .to raise_error(DeepL::Exceptions::ValidationError)
+        expect { client.replace_spoken_terms_list('st-1', { lang: 'en', entries: bad }) }
+          .to raise_error(DeepL::Exceptions::ValidationError)
+        expect(a_request(:any, /.*/)).not_to have_been_made
+      end
+    end
+  end
+
+  describe '#list_spoken_terms and #get_spoken_terms' do
+    it 'send GET requests without a body' do
+      stub_request(:get, url('/v3/spoken-terms')).with(headers: json_headers, body: no_body)
+                                                 .to_return(reply(spoken_terms: [collection_json]))
+      stub_request(:get, url('/v3/spoken-terms/st-1')).with(headers: json_headers, body: no_body)
+                                                      .to_return(reply(collection_json))
+
+      expect(client.list_spoken_terms.map(&:spoken_terms_id)).to eq(['st-1'])
+      expect(client.get_spoken_terms('st-1').name).to eq('terms')
+    end
+
+    it 'turns a missing term_lists into an empty list' do
+      stub_request(:get, url('/v3/spoken-terms'))
+        .to_return(reply(spoken_terms: [collection_json.reject { |k, _| k == :term_lists }]))
+
+      expect(client.list_spoken_terms.map(&:term_lists)).to eq([[]])
+    end
+  end
+
+  describe '#update_spoken_terms' do
+    it 'sends only the given arguments' do
+      stub_request(:patch, url('/v3/spoken-terms/st-1'))
+        .with(body: { term_lists: [{ lang: 'en', entries: 'c' }] }, headers: json_headers)
+        .to_return(reply(collection_json))
+      stub_request(:patch, url('/v3/spoken-terms/st-1')).with(body: { name: 'new' })
+                                                        .to_return(reply(collection_json))
+
+      client.update_spoken_terms('st-1', term_lists: [{ lang: 'en', entries: ['c'] }])
+      client.update_spoken_terms('st-1', name: 'new')
+    end
+
+    it 'sends the extra body parameters' do
+      stub_request(:patch, url('/v3/spoken-terms/st-1'))
+        .with(body: { name: 'new', beta: true }).to_return(reply(collection_json))
+
+      client.update_spoken_terms('st-1', name: 'new', extra_body_parameters: { beta: true })
+    end
+
+    it 'sends an empty object when no argument is given' do
+      stub_request(:patch, url('/v3/spoken-terms/st-1')).with(body: '{}')
+                                                        .to_return(reply(collection_json))
+
+      client.update_spoken_terms('st-1')
+    end
+  end
+
+  describe '#get_spoken_terms_entries' do
+    it 'sends the language in the query and splits the entries on newlines' do
+      stub_request(:get, url('/v3/spoken-terms/st-1/entries?lang=en'))
+        .with(headers: json_headers).to_return(reply(lang: 'en', entries: "a\nb\n"))
+
+      result = client.get_spoken_terms_entries('st-1', 'en')
+
+      expect([result.lang, result.entries]).to eq(['en', %w[a b]])
+    end
+  end
+
+  describe '#replace_spoken_terms_list' do
+    it 'takes a SpokenTermsEntries and a SpokenTerms object' do
+      stub_request(:put, url('/v3/spoken-terms/st-1/term-lists'))
+        .with(body: { lang: 'en', entries: "a\nb" }, headers: json_headers)
+        .to_return(reply(lang: 'en', entry_count: 2))
+
+      list = client.replace_spoken_terms_list(
+        collection, DeepL::Resources::SpokenTermsEntries.new('en', %w[a b])
+      )
+
+      expect([list.lang, list.entry_count]).to eq(['en', 2])
+    end
+
+    it 'takes a hash and sends the extra body parameters' do
+      stub_request(:put, url('/v3/spoken-terms/st-1/term-lists'))
+        .with(body: { lang: 'de', entries: 'x', beta: true })
+        .to_return(reply(lang: 'de', entry_count: 1))
+
+      client.replace_spoken_terms_list('st-1', { lang: 'de', entries: ['x'] },
+                                       extra_body_parameters: { beta: true })
+    end
+  end
+
+  describe '#delete_spoken_terms and #delete_spoken_terms_list' do
+    it 'send DELETE requests without a body and return nil' do
+      stub_request(:delete, url('/v3/spoken-terms/st-1/term-lists?lang=de'))
+        .with(headers: json_headers, body: no_body).to_return(status: 204)
+      stub_request(:delete, url('/v3/spoken-terms/st-1'))
+        .with(headers: json_headers, body: no_body).to_return(status: 204)
+
+      expect(client.delete_spoken_terms_list('st-1', 'de')).to be_nil
+      expect(client.delete_spoken_terms('st-1')).to be_nil
+    end
+  end
+
+  describe 'collection IDs' do
+    before do
+      encoded = url('/v3/spoken-terms/a%20b%2Fc')
+      stub_request(:get, encoded).to_return(reply(collection_json))
+      stub_request(:patch, encoded).to_return(reply(collection_json))
+      stub_request(:delete, encoded).to_return(status: 204)
+      stub_request(:get, "#{encoded}/entries?lang=en").to_return(reply(lang: 'en', entries: ''))
+      stub_request(:put, "#{encoded}/term-lists").to_return(reply(lang: 'en', entry_count: 0))
+      stub_request(:delete, "#{encoded}/term-lists?lang=en").to_return(status: 204)
+    end
+
+    it 'are URL-encoded in every path' do
+      id = 'a b/c'
+      client.get_spoken_terms(id)
+      client.update_spoken_terms(id, name: 'x')
+      client.delete_spoken_terms(id)
+      client.get_spoken_terms_entries(id, 'en')
+      client.replace_spoken_terms_list(id, { lang: 'en', entries: ['x'] })
+      client.delete_spoken_terms_list(id, 'en')
+    end
+  end
+end

data/spec/offline/style_profiles_spec.rb

@@ -0,0 +1,266 @@
+# 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'
+
+# The client has its own key and server, different from the module configuration, so a request
+# that falls back to module state hits no stub.
+describe 'DeepL::Client style profiles' do
+  let(:client) { DeepL::Client.new('client-key', server_url: 'https://client.example.test') }
+  let(:profile_id) { '3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47' }
+  let(:profile_path) { "/v3/style_profiles/#{profile_id}" }
+  # The full example of the API specification.
+  let(:profile_json) do
+    { style_profile_id: profile_id, name: 'Legal, German',
+      description: 'Contract wording for the German market.', industry: 'Legal',
+      glossary_ids: ['4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81'],
+      style_rule_ids: ['bd0a38f3-1831-440b-a8dd-2c702e2325ab'],
+      translation_memory_ids: ['a74d88fb-ed2a-4943-a664-a4512398b994'],
+      glossary_priority_order_enabled: true,
+      creation_time: '2026-04-01T16:34:25.223Z', updated_time: '2026-08-06T09:12:44.108Z' }
+  end
+  let(:bare_profile_json) do
+    { style_profile_id: 'c58e2a71-90b4-4d6f-a2e3-71d5c8b4f902', name: 'Marketing, Japanese',
+      glossary_ids: [], style_rule_ids: [], translation_memory_ids: [],
+      glossary_priority_order_enabled: false,
+      creation_time: '2026-07-14T11:02:09.640Z', updated_time: '2026-07-14T11:02:09.640Z' }
+  end
+
+  def url(path)
+    "https://client.example.test#{path}"
+  end
+
+  def json_headers
+    { 'Authorization' => 'DeepL-Auth-Key client-key', 'Content-Type' => 'application/json' }
+  end
+
+  def profile_object
+    DeepL::Resources::StyleProfile.new(profile_json.transform_keys(&:to_s), nil, nil)
+  end
+
+  def glossary
+    DeepL::Resources::Glossary.new({ 'glossary_id' => 'g1', 'name' => 'n' }, nil, nil)
+  end
+
+  def multilingual_glossary
+    DeepL::Resources::MultilingualGlossary.new({ 'glossary_id' => 'g3', 'name' => 'n' }, nil, nil)
+  end
+
+  def style_rule
+    DeepL::Resources::StyleRule.new({ 'style_id' => 's1', 'name' => 'n' }, nil, nil)
+  end
+
+  def translation_memory
+    DeepL::Resources::TranslationMemory.new({ 'translation_memory_id' => 't2', 'name' => 'n' },
+                                            nil, nil)
+  end
+
+  describe '#list_style_profiles' do
+    it 'sends no query without paging options and returns the profiles as an array' do
+      list_json = { style_profiles: [profile_json, bare_profile_json], total_count: 2 }
+      stub_request(:get, url('/v3/style_profiles')).with(headers: json_headers)
+                                                   .to_return(reply(list_json))
+
+      profiles = client.list_style_profiles
+
+      expect(profiles.map(&:name)).to eq(['Legal, German', 'Marketing, Japanese'])
+    end
+
+    it 'sends page and page_size as query parameters' do
+      stub_request(:get, url('/v3/style_profiles?page=2&page_size=100'))
+        .to_return(reply(style_profiles: [], total_count: 0))
+
+      expect(client.list_style_profiles(page: 2, page_size: 100)).to eq([])
+    end
+
+    it 'returns an empty array when style_profiles is missing' do
+      stub_request(:get, url('/v3/style_profiles')).to_return(reply(total_count: 0))
+
+      expect(client.list_style_profiles).to eq([])
+    end
+  end
+
+  describe '#create_style_profile' do
+    it 'sends only the name when no component is given' do
+      stub_request(:post, url('/v3/style_profiles'))
+        .with(body: { name: 'profile' }.to_json, headers: json_headers)
+        .to_return(reply(bare_profile_json, 201))
+
+      client.create_style_profile('profile')
+    end
+
+    it 'sends every field, the ID arrays in order and the boolean as JSON true' do
+      body = { name: 'profile', description: 'd', industry: 'Legal',
+               glossary_ids: %w[g2 g1], style_rule_ids: %w[s1], translation_memory_ids: %w[t1],
+               glossary_priority_order_enabled: true }
+      stub_request(:post, url('/v3/style_profiles'))
+        .with { |request| JSON.parse(request.body) == JSON.parse(body.to_json) }
+        .to_return(reply(profile_json, 201))
+
+      client.create_style_profile('profile', description: 'd', industry: 'Legal',
+                                             glossary_ids: %w[g2 g1], style_rule_ids: %w[s1],
+                                             translation_memory_ids: %w[t1],
+                                             glossary_priority_order_enabled: true)
+    end
+
+    it 'sends the IDs of glossary, style rule and translation memory objects' do
+      body = { name: 'profile', glossary_ids: %w[g1 g2 g3], style_rule_ids: %w[s1 s2],
+               translation_memory_ids: %w[t1 t2] }
+      stub_request(:post, url('/v3/style_profiles')).with(body: body.to_json)
+                                                    .to_return(reply(profile_json, 201))
+
+      client.create_style_profile('profile', glossary_ids: [glossary, 'g2', multilingual_glossary],
+                                             style_rule_ids: [style_rule, 's2'],
+                                             translation_memory_ids: ['t1', translation_memory])
+    end
+
+    it 'applies extra body parameters' do
+      stub_request(:post, url('/v3/style_profiles'))
+        .with(body: { name: 'profile', beta: 'x' }.to_json)
+        .to_return(reply(bare_profile_json, 201))
+
+      client.create_style_profile('profile', extra_body_parameters: { beta: 'x' })
+    end
+  end
+
+  describe '#get_style_profile' do
+    it 'accepts an ID string or a style profile object' do
+      stub_request(:get, url(profile_path)).with(headers: json_headers)
+                                           .to_return(reply(profile_json)).times(2)
+
+      expect(client.get_style_profile(profile_id).style_profile_id).to eq(profile_id)
+      expect(client.get_style_profile(profile_object).style_profile_id).to eq(profile_id)
+    end
+
+    it 'escapes the ID in the path' do
+      stub_request(:get, url('/v3/style_profiles/a%2Fb%20c')).to_return(reply(profile_json))
+
+      client.get_style_profile('a/b c')
+    end
+
+    it 'raises NotFound on 404' do
+      stub_request(:get, url(profile_path))
+        .to_return(reply({ message: 'Style profile not found' }, 404))
+
+      expect { client.get_style_profile(profile_id) }.to raise_error(DeepL::Exceptions::NotFound)
+    end
+  end
+
+  describe '#update_style_profile' do
+    it 'sends only the set fields, including an empty string and an empty array' do
+      stub_request(:patch, url(profile_path))
+        .with(body: { name: 'new', description: '', style_rule_ids: [] }.to_json,
+              headers: json_headers)
+        .to_return(reply(profile_json))
+
+      client.update_style_profile(profile_id, name: 'new', description: '', style_rule_ids: [])
+    end
+
+    it 'sends an empty object when nothing is set, also for a style profile object' do
+      stub_request(:patch, url(profile_path)).with(body: '{}').to_return(reply(profile_json))
+                                             .times(2)
+
+      client.update_style_profile(profile_id)
+      client.update_style_profile(profile_object)
+    end
+
+    it 'sends the IDs of component objects' do
+      body = { glossary_ids: %w[g1 g3], style_rule_ids: %w[s1], translation_memory_ids: %w[t2] }
+      stub_request(:patch, url(profile_path)).with(body: body.to_json)
+                                             .to_return(reply(profile_json))
+
+      client.update_style_profile(profile_id, glossary_ids: [glossary, multilingual_glossary],
+                                              style_rule_ids: [style_rule],
+                                              translation_memory_ids: [translation_memory])
+    end
+
+    it 'sends glossary_priority_order_enabled false as JSON false' do
+      stub_request(:patch, url(profile_path))
+        .with(body: { glossary_priority_order_enabled: false }.to_json)
+        .to_return(reply(profile_json))
+
+      client.update_style_profile(profile_id, glossary_priority_order_enabled: false)
+    end
+  end
+
+  describe '#delete_style_profile' do
+    it 'sends DELETE for an ID string or a style profile object and returns nil' do
+      stub_request(:delete, url(profile_path)).with(headers: json_headers)
+                                              .to_return(status: 204).times(2)
+
+      expect(client.delete_style_profile(profile_id)).to be_nil
+      expect(client.delete_style_profile(profile_object)).to be_nil
+    end
+  end
+
+  describe 'empty ID' do
+    it 'raises ArgumentError and sends no request' do
+      ['', nil].each do |id|
+        expect { client.get_style_profile(id) }.to raise_error(ArgumentError)
+        expect { client.update_style_profile(id, name: 'x') }.to raise_error(ArgumentError)
+        expect { client.delete_style_profile(id) }.to raise_error(ArgumentError)
+      end
+      expect(a_request(:any, /.*/)).not_to have_been_made
+    end
+  end
+
+  describe 'parsing' do
+    it 'parses every field of the specification example' do
+      stub_request(:get, url(profile_path)).to_return(reply(profile_json))
+
+      times = { creation_time: Time.utc(2026, 4, 1, 16, 34, Rational(25_223, 1000)),
+                updated_time: Time.utc(2026, 8, 6, 9, 12, Rational(44_108, 1000)) }
+      expected = profile_json.merge(times)
+      expect(client.get_style_profile(profile_id)).to have_attributes(expected)
+    end
+
+    it 'parses a profile without description and industry, and ignores unknown fields' do
+      stub_request(:get, url(profile_path)).to_return(
+        reply(bare_profile_json.merge(example_document_ids: ['e1'], spoken_terms_ids: ['s1']))
+      )
+
+      profile = client.get_style_profile(profile_id)
+
+      expect(profile.description).to be_nil
+      expect(profile.industry).to be_nil
+      expect(profile.glossary_priority_order_enabled).to be(false)
+      expect(profile).not_to respond_to(:example_document_ids)
+      expect(profile).not_to respond_to(:spoken_terms_ids)
+    end
+
+    it 'parses a timestamp with 7 fractional digits' do
+      stub_request(:get, url(profile_path))
+        .to_return(reply(bare_profile_json.merge(creation_time: '2026-10-26T16:27:10.2982869Z')))
+
+      expect(client.get_style_profile(profile_id).creation_time)
+        .to eq(Time.utc(2026, 10, 26, 16, 27, Rational(102_982_869, 10_000_000)))
+    end
+
+    it 'defaults missing ID lists and the boolean' do
+      stub_request(:get, url(profile_path))
+        .to_return(reply(style_profile_id: profile_id, name: 'n', glossary_ids: nil))
+
+      profile = client.get_style_profile(profile_id)
+
+      expect([profile.glossary_ids, profile.style_rule_ids, profile.translation_memory_ids])
+        .to eq([[], [], []])
+      expect(profile.glossary_priority_order_enabled).to be(false)
+    end
+
+    it 'turns malformed values into nil or skips them without failing the call' do
+      stub_request(:get, url(profile_path)).to_return(
+        reply(profile_json.merge(creation_time: 'not a timestamp', glossary_ids: ['g1', 7, nil]))
+      )
+
+      profile = client.get_style_profile(profile_id)
+
+      expect(profile.creation_time).to be_nil
+      expect(profile.glossary_ids).to eq(['g1'])
+      expect(profile.name).to eq('Legal, German')
+      expect(profile.style_rule_ids).to eq(['bd0a38f3-1831-440b-a8dd-2c702e2325ab'])
+      expect(profile.updated_time).to eq(Time.utc(2026, 8, 6, 9, 12, Rational(44_108, 1000)))
+    end
+  end
+end