deepl-rb 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1de43b1593c5b5d4236c0b064c08436ab57fe13bf3fdc29069220fd899ca8e1d
-  data.tar.gz: a486d446fa3bebddbf3fd6aa468300bead03eafe8bc075c33a28d80be6e555b8
+  metadata.gz: 47bf797967929a4b7775e21ce7021cdc1871283b3358cbb36d13a8f6f6b5ac6b
+  data.tar.gz: df4399cc6c552fb5c03b79b0566d2370101b58246bfd5e0b05d27c83e994ae6c
 SHA512:
-  metadata.gz: ca167089f7a190915436fb316a8a82aa69bf8093316b4074c6536bb21e002811d9bdd57fc8711eeb634025b094a9fe17e2b057eee5ea5d2499539060e09b8ebd
-  data.tar.gz: 1c63cd745170652f01a2335cc064ceb0266c1584a19bd1fcd6683c6d461241b646d33df0b3e36f516e1dff6a1d6158e706994b862b6bd8d671b1db399cabfa03
+  metadata.gz: 4639c87e107dfa0a13b1bace938e9a3580fb15bb1e2f280267527e3d5d0c9b8913752b841bd095039f1e4f7d15b13813075131c0767216855bf5e7d28a4b81a1
+  data.tar.gz: 19743f57e84c550e5fe35b1d6c39f853df1d0d1d357eb8c0f061a0202831af8a557651f34f50dcad10928b45638a3a09b9ab64652fdadab6d6ad62ec3f2a1242

data/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.0]
+### Added
+* Added `rephrase` functionality to get a new version of submitted text with various possible styles or tones applied
+* Added `DeepL::Constants` namespace and associated constant values for options possibilities
 
 ## [3.1.0]
 ### Added
@@ -50,7 +54,7 @@ The change in major version is only due to the change in maintainership, there i
 ### Fixed
 * Make RequestEntityTooLarge error message more clear
 
-
+[3.2.0]: https://github.com/DeepLcom/deepl-rb/compare/v3.1.0...3.2.0
 [3.1.0]: https://github.com/DeepLcom/deepl-rb/compare/v3.0.2...v3.1.0
 [3.0.2]: https://github.com/DeepLcom/deepl-rb/compare/v3.0.1...v3.0.2
 [3.0.1]: https://github.com/DeepLcom/deepl-rb/compare/v3.0.0...v3.0.1

data/README.md

@@ -168,6 +168,37 @@ The following parameters will be automatically converted:
 | `glossary_id`         | No conversion applied
 | `context`             | No conversion applied
 
+### Rephrase Text
+
+To rephrase or improve text, including changing the writing style or tone of the text, use the `rephrase` method:
+
+```rb
+rephrased_text = DeepL.rephrase 'you will acquire new rephrased text', 'EN'
+
+puts rephrased_text.class
+# => DeepL::Resources::Text
+puts rephrased_text.text
+# => 'You get new rephrased text.'
+```
+
+As with translate, the text input can be a single string or an array of strings.
+
+You can use the additional arguments to specify the writing style or tone you want for the rephrased text:
+
+```rb
+rephrased_text = DeepL.rephrase 'you will acquire new rephrased text', 'EN', 'casual'
+
+puts rephrased_text.text
+# => 'You'll get new, rephrased text.'
+```
+
+```rb
+rephrased_text = DeepL.rephrase 'you will acquire new rephrased text', 'EN', nil, 'friendly'
+
+puts rephrased_text.text
+# => 'You'll get to enjoy new, rephrased text!'
+```
+
 ### Glossaries
 
 To create a glossary, use the `glossaries.create` method. The glossary `entries` argument should be an array of text pairs. Each pair includes the source and the target translations.
@@ -389,6 +420,30 @@ end
 
 This information is passed along when the library makes calls to the DeepL API. Both name and version are required. Please note that setting the `User-Agent` header via `deepl.configure` will override this setting, if you need to use this, please manually identify your Application in the `User-Agent` header.
 
+## Options Constants
+
+The available values for various possible options are provided under the `DeepL::Constants` namespace. The currently available options are
+
+`TagHandling`
+`SplitSentences`
+`ModelType`
+`Formality`
+`WritingStyle`
+`Tone`
+
+To view all the possible options for a given constant, call `options`:
+
+```rb
+all_available_tones = DeepL::Constants::Tones.options
+```
+
+To check if a given string is a possible option for a given constant, call `valid?`:
+
+```rb
+DeepL::Constants::Tones.valid?('friendly') # true
+DeepL::Constants::Tones.valid?('rude') # false
+```
+
 ## Integrations
 
 ### Ruby on Rails

data/VERSION

@@ -1 +1 @@
-3.1.0
+3.2.0

data/deepl-rb.gemspec

@@ -2,17 +2,17 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Juwelier::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: deepl-rb 3.1.0 ruby lib
+# stub: deepl-rb 3.2.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "deepl-rb".freeze
-  s.version = "3.1.0"
+  s.version = "3.2.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.metadata = { "bug_tracker_uri" => "https://github.com/DeepLcom/deepl-rb/issues", "changelog_uri" => "https://github.com/DeepLcom/deepl-rb/blob/main/CHANGELOG.md", "documentation_uri" => "https://github.com/DeepLcom/deepl-rb/blob/main/README.md", "homepage_uri" => "https://github.com/DeepLcom/deepl-rb" } if s.respond_to? :metadata=
   s.require_paths = ["lib".freeze]
   s.authors = ["DeepL SE".freeze]
-  s.date = "2024-11-15"
+  s.date = "2025-01-15"
   s.description = "Official Ruby library for the DeepL language translation API (v2). For more information, check this: https://www.deepl.com/docs/api-reference.html".freeze
   s.email = "open-source@deepl.com".freeze
   s.extra_rdoc_files = [
@@ -39,6 +39,13 @@ Gem::Specification.new do |s|
     "lib/deepl.rb",
     "lib/deepl/api.rb",
     "lib/deepl/configuration.rb",
+    "lib/deepl/constants/base_constant.rb",
+    "lib/deepl/constants/formality.rb",
+    "lib/deepl/constants/model_type.rb",
+    "lib/deepl/constants/split_sentences.rb",
+    "lib/deepl/constants/tag_handling.rb",
+    "lib/deepl/constants/tone.rb",
+    "lib/deepl/constants/writing_style.rb",
     "lib/deepl/document_api.rb",
     "lib/deepl/exceptions/authorization_failed.rb",
     "lib/deepl/exceptions/bad_request.rb",
@@ -63,6 +70,7 @@ Gem::Specification.new do |s|
     "lib/deepl/requests/glossary/language_pairs.rb",
     "lib/deepl/requests/glossary/list.rb",
     "lib/deepl/requests/languages.rb",
+    "lib/deepl/requests/rephrase.rb",
     "lib/deepl/requests/translate.rb",
     "lib/deepl/requests/usage.rb",
     "lib/deepl/resources/base.rb",
@@ -80,6 +88,7 @@ Gem::Specification.new do |s|
     "spec/api/api_spec.rb",
     "spec/api/configuration_spec.rb",
     "spec/api/deepl_spec.rb",
+    "spec/constants/constants_spec.rb",
     "spec/fixtures/vcr_cassettes/deepl_document.yml",
     "spec/fixtures/vcr_cassettes/deepl_document_download.yml",
     "spec/fixtures/vcr_cassettes/deepl_glossaries.yml",
@@ -88,6 +97,7 @@ Gem::Specification.new do |s|
     "spec/fixtures/vcr_cassettes/deepl_usage.yml",
     "spec/fixtures/vcr_cassettes/glossaries.yml",
     "spec/fixtures/vcr_cassettes/languages.yml",
+    "spec/fixtures/vcr_cassettes/rephrase_texts.yml",
     "spec/fixtures/vcr_cassettes/translate_texts.yml",
     "spec/fixtures/vcr_cassettes/usage.yml",
     "spec/integration_tests/document_api_spec.rb",
@@ -99,6 +109,7 @@ Gem::Specification.new do |s|
     "spec/requests/glossary/language_pairs_spec.rb",
     "spec/requests/glossary/list_spec.rb",
     "spec/requests/languages_spec.rb",
+    "spec/requests/rephrase_spec.rb",
     "spec/requests/translate_spec.rb",
     "spec/requests/usage_spec.rb",
     "spec/resources/glossary_spec.rb",
@@ -110,12 +121,12 @@ Gem::Specification.new do |s|
   ]
   s.homepage = "https://github.com/DeepLcom/deepl-rb".freeze
   s.licenses = ["MIT".freeze]
-  s.rubygems_version = "3.4.6".freeze
+  s.rubygems_version = "3.5.3".freeze
   s.summary = "Official Ruby library for the DeepL language translation API.".freeze
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<juwelier>.freeze, [">= 0"])
-  s.add_development_dependency(%q<byebug>.freeze, [">= 0"])
+  s.add_development_dependency(%q<juwelier>.freeze, [">= 0".freeze])
+  s.add_development_dependency(%q<byebug>.freeze, [">= 0".freeze])
 end
 

data/lib/deepl/constants/base_constant.rb

@@ -0,0 +1,18 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Constants
+    class BaseConstant
+      def self.options
+        constants.map { |const| const_get(const) }
+      end
+
+      def self.valid?(value)
+        options.include?(value)
+      end
+    end
+  end
+end

data/lib/deepl/constants/formality.rb

@@ -0,0 +1,16 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Constants
+    class Formality < BaseConstant
+      DEFAULT = 'default'
+      MORE = 'more'
+      LESS = 'less'
+      PREFER_MORE = 'prefer_more'
+      PREFER_LESS = 'prefer_less'
+    end
+  end
+end

data/lib/deepl/constants/model_type.rb

@@ -0,0 +1,14 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Constants
+    class ModelType < BaseConstant
+      QUALITY_OPTIMIZED = 'quality_optimized'
+      PREFER_QUALITY_OPTIMIZED = 'prefer_quality_optimized'
+      LATENCY_OPTIMIZED = 'latency_optimized'
+    end
+  end
+end

data/lib/deepl/constants/split_sentences.rb

@@ -0,0 +1,14 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Constants
+    class SplitSentences < BaseConstant
+      NO_SPLITTING = '0'
+      SPLIT_ON_PUNCTUATION_AND_NEWLINES = '1'
+      SPLIT_ON_PUNCTUATION_ONLY = 'nonewlines'
+    end
+  end
+end

data/lib/deepl/constants/tag_handling.rb

@@ -0,0 +1,13 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Constants
+    class TagHandling < BaseConstant
+      XML = 'xml'
+      HTML = 'html'
+    end
+  end
+end

data/lib/deepl/constants/tone.rb

@@ -0,0 +1,20 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Constants
+    class Tone < BaseConstant
+      DEFAULT = 'default'
+      ENTHUSIASTIC = 'enthusiastic'
+      FRIENDLY = 'friendly'
+      CONFIDENT = 'confident'
+      DIPLOMATIC = 'diplomatic'
+      PREFER_ENTHUSIASTIC = 'prefer_enthusiastic'
+      PREFER_FRIENDLY = 'prefer_friendly'
+      PREFER_CONFIDENT = 'prefer_confident'
+      PREFER_DIPLOMATIC = 'prefer_diplomatic'
+    end
+  end
+end

data/lib/deepl/constants/writing_style.rb

@@ -0,0 +1,20 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Constants
+    class WritingStyle < BaseConstant
+      DEFAULT = 'default'
+      SIMPLE = 'simple'
+      BUSINESS = 'business'
+      ACADEMIC = 'academic'
+      CASUAL = 'casual'
+      PREFER_SIMPLE = 'prefer_simple'
+      PREFER_BUSINESS = 'prefer_business'
+      PREFER_ACADEMIC = 'prefer_academic'
+      PREFER_CASUAL = 'prefer_casual'
+    end
+  end
+end

data/lib/deepl/requests/rephrase.rb

@@ -0,0 +1,54 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Requests
+    class Rephrase < Base
+      attr_reader :text, :target_lang, :writing_style, :tone
+
+      def initialize(api, text, target_lang, writing_style = nil, tone = nil, options = {})
+        super(api, options)
+        @text = text
+        @target_lang = target_lang
+        @writing_style = writing_style
+        @tone = tone
+      end
+
+      def request
+        text_arrayified = text.is_a?(Array) ? text : [text]
+        payload = { text: text_arrayified, target_lang: target_lang }
+        payload[:writing_style] = writing_style unless writing_style.nil?
+        payload[:tone] = tone unless tone.nil?
+        build_texts(*execute_request_with_retries(post_request(payload)))
+      end
+
+      def details
+        "HTTP Headers: #{headers}\nPayload #{{ text: text, target_lang: target_lang,
+                                               writing_style: writing_style, tone: tone }}"
+      end
+
+      def to_s
+        "POST #{uri.request_uri}"
+      end
+
+      private
+
+      def build_texts(request, response)
+        data = JSON.parse(response.body)
+
+        texts = data['improvements'].map do |improvement|
+          Resources::Text.new(improvement['text'], improvement['detected_source_language'], nil,
+                              request, response)
+        end
+
+        texts.size == 1 ? texts.first : texts
+      end
+
+      def path
+        'write/rephrase'
+      end
+    end
+  end
+end

data/lib/deepl.rb

@@ -34,6 +34,7 @@ require 'deepl/requests/glossary/list'
 require 'deepl/requests/languages'
 require 'deepl/requests/translate'
 require 'deepl/requests/usage'
+require 'deepl/requests/rephrase'
 
 # -- Responses and resources
 require 'deepl/resources/base'
@@ -49,6 +50,15 @@ require 'deepl/resources/usage'
 require 'deepl/utils/exception_builder'
 require 'deepl/utils/backoff_timer'
 
+# -- Constants
+require 'deepl/constants/base_constant'
+require 'deepl/constants/formality'
+require 'deepl/constants/model_type'
+require 'deepl/constants/split_sentences'
+require 'deepl/constants/tag_handling'
+require 'deepl/constants/tone'
+require 'deepl/constants/writing_style'
+
 # -- HTTP Utils
 require 'http_client_options'
 

data/spec/constants/constants_spec.rb

@@ -0,0 +1,158 @@
+# Copyright 2025 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::Constants' do
+  describe DeepL::Constants::Tone do
+    subject(:tone) { described_class }
+
+    it 'includes all expected tone values' do # rubocop:disable RSpec/ExampleLength
+      expect(tone.options).to contain_exactly(
+        'confident',
+        'default',
+        'diplomatic',
+        'enthusiastic',
+        'friendly',
+        'prefer_confident',
+        'prefer_diplomatic',
+        'prefer_enthusiastic',
+        'prefer_friendly'
+      )
+    end
+
+    it 'validates correct tone values' do
+      expect(tone.valid?('enthusiastic')).to be true
+      expect(tone.valid?('friendly')).to be true
+      expect(tone.valid?('confident')).to be true
+      expect(tone.valid?('diplomatic')).to be true
+      expect(tone.valid?('default')).to be true
+    end
+
+    it 'invalidates incorrect tone values' do
+      expect(tone.valid?('angry')).to be false
+      expect(tone.valid?('')).to be false
+      expect(tone.valid?(nil)).to be false
+    end
+  end
+
+  describe DeepL::Constants::WritingStyle do
+    subject(:writing_style) { described_class }
+
+    it 'includes all expected writing style values' do # rubocop:disable RSpec/ExampleLength
+      expect(writing_style.options).to contain_exactly(
+        'default',
+        'simple',
+        'business',
+        'academic',
+        'casual',
+        'prefer_academic',
+        'prefer_business',
+        'prefer_casual',
+        'prefer_simple'
+      )
+    end
+
+    it 'validates correct writing style values' do
+      expect(writing_style.valid?('simple')).to be true
+      expect(writing_style.valid?('business')).to be true
+      expect(writing_style.valid?('academic')).to be true
+      expect(writing_style.valid?('casual')).to be true
+      expect(writing_style.valid?('default')).to be true
+    end
+
+    it 'invalidates incorrect writing style values' do
+      expect(writing_style.valid?('wordy')).to be false
+      expect(writing_style.valid?('')).to be false
+      expect(writing_style.valid?(nil)).to be false
+    end
+  end
+
+  describe DeepL::Constants::TagHandling do
+    subject(:tag_handling) { described_class }
+
+    it 'includes all expected tag handling values' do
+      expect(tag_handling.options).to contain_exactly('xml', 'html')
+    end
+
+    it 'validates correct tag handling values' do
+      expect(tag_handling.valid?('xml')).to be true
+      expect(tag_handling.valid?('html')).to be true
+    end
+
+    it 'invalidates incorrect tag handling values' do
+      expect(tag_handling.valid?('json')).to be false
+      expect(tag_handling.valid?('')).to be false
+      expect(tag_handling.valid?(nil)).to be false
+    end
+  end
+
+  describe DeepL::Constants::SplitSentences do
+    subject(:split_sentences) { described_class }
+
+    it 'includes all expected split sentences values' do
+      expect(split_sentences.options).to contain_exactly('0', '1', 'nonewlines')
+    end
+
+    it 'validates correct split sentences values' do
+      expect(split_sentences.valid?('0')).to be true
+      expect(split_sentences.valid?('1')).to be true
+      expect(split_sentences.valid?('nonewlines')).to be true
+    end
+
+    it 'invalidates incorrect split sentences values' do
+      expect(split_sentences.valid?('2')).to be false
+      expect(split_sentences.valid?('')).to be false
+      expect(split_sentences.valid?(nil)).to be false
+    end
+  end
+
+  describe DeepL::Constants::ModelType do
+    subject(:model_type) { described_class }
+
+    it 'includes all expected model type values' do
+      expect(model_type.options).to contain_exactly(
+        'quality_optimized',
+        'prefer_quality_optimized',
+        'latency_optimized'
+      )
+    end
+
+    it 'validates correct model type values' do
+      expect(model_type.valid?('quality_optimized')).to be true
+      expect(model_type.valid?('prefer_quality_optimized')).to be true
+      expect(model_type.valid?('latency_optimized')).to be true
+    end
+
+    it 'invalidates incorrect model type values' do
+      expect(model_type.valid?('speed_optimized')).to be false
+      expect(model_type.valid?('')).to be false
+      expect(model_type.valid?(nil)).to be false
+    end
+  end
+
+  describe DeepL::Constants::Formality do
+    subject(:formality) { described_class }
+
+    it 'includes all expected formality values' do
+      expect(formality.options).to contain_exactly('default', 'more', 'less', 'prefer_more',
+                                                   'prefer_less')
+    end
+
+    it 'validates correct formality values' do
+      expect(formality.valid?('default')).to be true
+      expect(formality.valid?('more')).to be true
+      expect(formality.valid?('less')).to be true
+      expect(formality.valid?('prefer_more')).to be true
+      expect(formality.valid?('prefer_less')).to be true
+    end
+
+    it 'invalidates incorrect formality values' do
+      expect(formality.valid?('neutral')).to be false
+      expect(formality.valid?('')).to be false
+      expect(formality.valid?(nil)).to be false
+    end
+  end
+end

data/spec/fixtures/vcr_cassettes/rephrase_texts.yml

@@ -0,0 +1,401 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://api.deepl.com/v2/write/rephrase
+    body:
+      encoding: UTF-8
+      string: '{"text":["As Gregor Samsa awoke one morning from uneasy dreams he found
+        himself transformed."],"target_lang":"EN"}'
+    headers:
+      Authorization:
+      - DeepL-Auth-Key VALID_TOKEN
+      User-Agent:
+      - deepl-ruby/3.0.2 (darwin24) ruby/3.3.0
+      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:
+      - Fri, 10 Jan 2025 07:00:45 GMT
+      Content-Type:
+      - application/json; charset=utf-8
+      Transfer-Encoding:
+      - chunked
+      Vary:
+      - Accept-Encoding
+      X-Trace-Id:
+      - '09daf98547c94050b68e39cf38b0fe7d'
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains; preload
+      Server-Timing:
+      - l7_lb_tls;dur=95, l7_lb_idle;dur=3, l7_lb_receive;dur=0, l7_lb_total;dur=378
+      Access-Control-Expose-Headers:
+      - Server-Timing, X-Trace-ID
+    body:
+      encoding: ASCII-8BIT
+      string: '{"improvements":[{"text":"When Gregor Samsa awoke one morning from
+        troubled dreams, he found himself transformed.","detected_source_language":"en","target_language":"en-US"}]}'
+  recorded_at: Fri, 10 Jan 2025 07:00:45 GMT
+- request:
+    method: post
+    uri: https://api.deepl.com/v2/write/rephrase
+    body:
+      encoding: UTF-8
+      string: '{"text":["As Gregor Samsa awoke one morning from uneasy dreams he found
+        himself transformed.","He lay on his armour-like back, and if he lifted his
+        head a little"],"target_lang":"EN"}'
+    headers:
+      Authorization:
+      - DeepL-Auth-Key VALID_TOKEN
+      User-Agent:
+      - deepl-ruby/3.0.2 (darwin24) ruby/3.3.0
+      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:
+      - Fri, 10 Jan 2025 07:00:45 GMT
+      Content-Type:
+      - application/json; charset=utf-8
+      Transfer-Encoding:
+      - chunked
+      Vary:
+      - Accept-Encoding
+      X-Trace-Id:
+      - df25db169c5f4c198ff7b5a319a16669
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains; preload
+      Server-Timing:
+      - l7_lb_tls;dur=95, l7_lb_idle;dur=0, l7_lb_receive;dur=0, l7_lb_total;dur=423
+      Access-Control-Expose-Headers:
+      - Server-Timing, X-Trace-ID
+    body:
+      encoding: ASCII-8BIT
+      string: '{"improvements":[{"text":"When Gregor Samsa awoke one morning from
+        troubled dreams, he found himself transformed.","detected_source_language":"en","target_language":"en-US"},{"text":"He
+        lay on his armor-like back, and when he lifted his head a little","detected_source_language":"en","target_language":"en-US"}]}'
+  recorded_at: Fri, 10 Jan 2025 07:00:45 GMT
+- request:
+    method: post
+    uri: https://api.deepl.com/v2/write/rephrase
+    body:
+      encoding: UTF-8
+      string: '{"text":["As Gregor Samsa awoke one morning from uneasy dreams he found
+        himself transformed."],"target_lang":"EN","tone":"friendly"}'
+    headers:
+      Authorization:
+      - DeepL-Auth-Key VALID_TOKEN
+      User-Agent:
+      - deepl-ruby/3.0.2 (darwin24) ruby/3.3.0
+      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:
+      - Fri, 10 Jan 2025 07:00:46 GMT
+      Content-Type:
+      - application/json; charset=utf-8
+      Transfer-Encoding:
+      - chunked
+      Vary:
+      - Accept-Encoding
+      X-Trace-Id:
+      - 14fdbaa36544495a993136451b65e52b
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains; preload
+      Server-Timing:
+      - l7_lb_tls;dur=94, l7_lb_idle;dur=0, l7_lb_receive;dur=0, l7_lb_total;dur=460
+      Access-Control-Expose-Headers:
+      - Server-Timing, X-Trace-ID
+    body:
+      encoding: ASCII-8BIT
+      string: '{"improvements":[{"text":"One morning, Gregor Samsa woke up from restless
+        dreams to find himself in a strange new form.","detected_source_language":"en","target_language":"en-US"}]}'
+  recorded_at: Fri, 10 Jan 2025 07:00:46 GMT
+- request:
+    method: post
+    uri: https://api.deepl.com/v2/write/rephrase
+    body:
+      encoding: UTF-8
+      string: '{"text":["As Gregor Samsa awoke one morning from uneasy dreams he found
+        himself transformed.","He lay on his armour-like back, and if he lifted his
+        head a little"],"target_lang":"EN","tone":"friendly"}'
+    headers:
+      Authorization:
+      - DeepL-Auth-Key VALID_TOKEN
+      User-Agent:
+      - deepl-ruby/3.0.2 (darwin24) ruby/3.3.0
+      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:
+      - Fri, 10 Jan 2025 07:00:46 GMT
+      Content-Type:
+      - application/json; charset=utf-8
+      Transfer-Encoding:
+      - chunked
+      Vary:
+      - Accept-Encoding
+      X-Trace-Id:
+      - a31d9cca4073414c9be843fffed914c3
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains; preload
+      Server-Timing:
+      - l7_lb_tls;dur=93, l7_lb_idle;dur=1, l7_lb_receive;dur=0, l7_lb_total;dur=413
+      Access-Control-Expose-Headers:
+      - Server-Timing, X-Trace-ID
+    body:
+      encoding: ASCII-8BIT
+      string: '{"improvements":[{"text":"One morning, Gregor Samsa woke up from restless
+        dreams to find himself in a strange new form.","detected_source_language":"en","target_language":"en-US"},{"text":"He
+        was lying on his armor-like back, and if he lifted his head just a little
+        bit...","detected_source_language":"en","target_language":"en-US"}]}'
+  recorded_at: Fri, 10 Jan 2025 07:00:47 GMT
+- request:
+    method: post
+    uri: https://api.deepl.com/v2/write/rephrase
+    body:
+      encoding: UTF-8
+      string: '{"text":["As Gregor Samsa awoke one morning from uneasy dreams he found
+        himself transformed."],"target_lang":"EN","writing_style":"business"}'
+    headers:
+      Authorization:
+      - DeepL-Auth-Key VALID_TOKEN
+      User-Agent:
+      - deepl-ruby/3.0.2 (darwin24) ruby/3.3.0
+      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:
+      - Fri, 10 Jan 2025 07:00:47 GMT
+      Content-Type:
+      - application/json; charset=utf-8
+      Transfer-Encoding:
+      - chunked
+      Vary:
+      - Accept-Encoding
+      X-Trace-Id:
+      - 58d0bbf1167f40b2a62f87c2a6d7dda3
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains; preload
+      Server-Timing:
+      - l7_lb_tls;dur=98, l7_lb_idle;dur=1, l7_lb_receive;dur=0, l7_lb_total;dur=385
+      Access-Control-Expose-Headers:
+      - Server-Timing, X-Trace-ID
+    body:
+      encoding: ASCII-8BIT
+      string: '{"improvements":[{"text":"Gregor Samsa awoke one morning, having had
+        disturbing dreams, to find himself transformed.","detected_source_language":"en","target_language":"en-US"}]}'
+  recorded_at: Fri, 10 Jan 2025 07:00:47 GMT
+- request:
+    method: post
+    uri: https://api.deepl.com/v2/write/rephrase
+    body:
+      encoding: UTF-8
+      string: '{"text":["As Gregor Samsa awoke one morning from uneasy dreams he found
+        himself transformed.","He lay on his armour-like back, and if he lifted his
+        head a little"],"target_lang":"EN","writing_style":"business"}'
+    headers:
+      Authorization:
+      - DeepL-Auth-Key VALID_TOKEN
+      User-Agent:
+      - deepl-ruby/3.0.2 (darwin24) ruby/3.3.0
+      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:
+      - Fri, 10 Jan 2025 07:00:48 GMT
+      Content-Type:
+      - application/json; charset=utf-8
+      Transfer-Encoding:
+      - chunked
+      Vary:
+      - Accept-Encoding
+      X-Trace-Id:
+      - 37a69ff78833465cbc9ddadd4f9aca36
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains; preload
+      Server-Timing:
+      - l7_lb_tls;dur=96, l7_lb_idle;dur=0, l7_lb_receive;dur=0, l7_lb_total;dur=374
+      Access-Control-Expose-Headers:
+      - Server-Timing, X-Trace-ID
+    body:
+      encoding: ASCII-8BIT
+      string: '{"improvements":[{"text":"Gregor Samsa awoke one morning, having had
+        disturbing dreams, to find himself transformed.","detected_source_language":"en","target_language":"en-US"},{"text":"He
+        was positioned on his back, which was similar to armor. If he lifted his head
+        slightly,","detected_source_language":"en","target_language":"en-US"}]}'
+  recorded_at: Fri, 10 Jan 2025 07:00:48 GMT
+- request:
+    method: post
+    uri: https://api.deepl.com/v2/write/rephrase
+    body:
+      encoding: UTF-8
+      string: '{"text":["As Gregor Samsa awoke one morning from uneasy dreams he found
+        himself transformed."],"target_lang":"EN","writing_style":"angry"}'
+    headers:
+      Authorization:
+      - DeepL-Auth-Key VALID_TOKEN
+      User-Agent:
+      - deepl-ruby/3.0.2 (darwin24) ruby/3.3.0
+      Content-Type:
+      - application/json
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Accept:
+      - "*/*"
+  response:
+    status:
+      code: 400
+      message: Bad Request
+    headers:
+      Date:
+      - Fri, 10 Jan 2025 07:00:48 GMT
+      Content-Type:
+      - application/json; charset=utf-8
+      Transfer-Encoding:
+      - chunked
+      X-Trace-Id:
+      - b406cc026c004d4c80d76131df636d8a
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains; preload
+      Server-Timing:
+      - l7_lb_tls;dur=98, l7_lb_idle;dur=1, l7_lb_receive;dur=0, l7_lb_total;dur=109
+      Access-Control-Expose-Headers:
+      - Server-Timing, X-Trace-ID
+    body:
+      encoding: UTF-8
+      string: '{"message":"Bad request. Reason: Unsupported value for field writing_style."}'
+  recorded_at: Fri, 10 Jan 2025 07:00:48 GMT
+- request:
+    method: post
+    uri: https://api.deepl.com/v2/write/rephrase
+    body:
+      encoding: UTF-8
+      string: '{"text":["As Gregor Samsa awoke one morning from uneasy dreams he found
+        himself transformed."],"target_lang":"EN","writing_style":"business","tone":"friendly"}'
+    headers:
+      Authorization:
+      - DeepL-Auth-Key VALID_TOKEN
+      User-Agent:
+      - deepl-ruby/3.0.2 (darwin24) ruby/3.3.0
+      Content-Type:
+      - application/json
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Accept:
+      - "*/*"
+  response:
+    status:
+      code: 400
+      message: Bad Request
+    headers:
+      Date:
+      - Fri, 10 Jan 2025 07:00:48 GMT
+      Content-Type:
+      - application/json; charset=utf-8
+      Transfer-Encoding:
+      - chunked
+      X-Trace-Id:
+      - 1b7680d714c24de49ded702b382c69b0
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains; preload
+      Server-Timing:
+      - l7_lb_tls;dur=98, l7_lb_idle;dur=1, l7_lb_receive;dur=0, l7_lb_total;dur=105
+      Access-Control-Expose-Headers:
+      - Server-Timing, X-Trace-ID
+    body:
+      encoding: UTF-8
+      string: '{"message":"Bad request. Reason: Both writing_style and tone defined.
+        Currently only style OR tone can be chosen for a single request.."}'
+  recorded_at: Fri, 10 Jan 2025 07:00:48 GMT
+- request:
+    method: post
+    uri: https://api.deepl.com/v2/write/rephrase
+    body:
+      encoding: UTF-8
+      string: '{"text":["As Gregor Samsa awoke one morning from uneasy dreams he found
+        himself transformed."],"target_lang":"EN"}'
+    headers:
+      Authorization:
+      - DeepL-Auth-Key invalid
+      User-Agent:
+      - deepl-ruby/3.0.2 (darwin24) ruby/3.3.0
+      Content-Type:
+      - application/json
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Accept:
+      - "*/*"
+  response:
+    status:
+      code: 403
+      message: Forbidden
+    headers:
+      Date:
+      - Fri, 10 Jan 2025 07:00:48 GMT
+      Content-Type:
+      - application/json; charset=utf-8
+      Transfer-Encoding:
+      - chunked
+      Vary:
+      - Accept-Encoding
+      X-Trace-Id:
+      - 568ef89e665f499ebcbc62b90ba09019
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains; preload
+      Server-Timing:
+      - l7_lb_tls;dur=121, l7_lb_idle;dur=1, l7_lb_receive;dur=0, l7_lb_total;dur=132
+      Access-Control-Expose-Headers:
+      - Server-Timing, X-Trace-ID
+    body:
+      encoding: ASCII-8BIT
+      string: '{"message":"Invalid API key."}'
+  recorded_at: Fri, 10 Jan 2025 07:00:48 GMT
+recorded_with: VCR 6.3.1

data/spec/requests/rephrase_spec.rb

@@ -0,0 +1,172 @@
+# Copyright 2025 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::Rephrase do
+  subject(:rephrase) { described_class.new(api, text, target_lang, writing_style, tone, 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(:text) do
+    'As Gregor Samsa awoke one morning from uneasy dreams he found himself transformed.'
+  end
+  let(:target_lang) { 'EN' }
+  let(:writing_style) { nil }
+  let(:tone) { nil }
+  let(:options) { {} }
+
+  describe '#request' do
+    around do |example|
+      VCR.use_cassette('rephrase_texts') { example.call }
+    end
+
+    context 'without a style or tone applied' do
+      context 'with a string as input' do
+        it 'returns a valid response as a DeepL Text resource' do
+          original_length = text.length
+          response_text = rephrase.request
+
+          expect(response_text).to be_a(DeepL::Resources::Text)
+          expect(response_text.text.length).not_to eq(original_length)
+          expect(response_text.detected_source_language.upcase).to eq('EN')
+        end
+      end
+
+      context 'with an array of texts as input' do
+        let(:text) do
+          [
+            'As Gregor Samsa awoke one morning from uneasy dreams he found himself transformed.',
+            'He lay on his armour-like back, and if he lifted his head a little'
+          ]
+        end
+
+        it 'returns a valid response as an array of DeepL Text resources' do
+          response_texts = rephrase.request
+
+          expect(response_texts).to all(be_a(DeepL::Resources::Text))
+          response_texts.each_with_index do |response_text, index|
+            expect(response_text.text.length).not_to eq(text[index].length)
+            expect(response_text.detected_source_language.upcase).to eq('EN')
+          end
+        end
+      end
+    end
+
+    context 'with a valid tone applied' do
+      let(:tone) { 'friendly' }
+
+      context 'with a string as input' do
+        it 'returns a valid response with a string as text input' do
+          original_length = text.length
+          response_text = rephrase.request
+
+          expect(response_text).to be_a(DeepL::Resources::Text)
+          expect(response_text.text.length).not_to eq(original_length)
+          expect(response_text.detected_source_language.upcase).to eq('EN')
+        end
+      end
+
+      context 'with an array of texts as input' do
+        let(:text) do
+          [
+            'As Gregor Samsa awoke one morning from uneasy dreams he found himself transformed.',
+            'He lay on his armour-like back, and if he lifted his head a little'
+          ]
+        end
+
+        it 'returns an array of valid text objects' do
+          response_texts = rephrase.request
+
+          expect(response_texts).to all(be_a(DeepL::Resources::Text))
+          response_texts.each_with_index do |response_text, index|
+            expect(response_text.text.length).not_to eq(text[index].length)
+            expect(response_text.detected_source_language.upcase).to eq('EN')
+          end
+        end
+      end
+    end
+
+    context 'with a valid writing style applied' do
+      let(:writing_style) { 'business' }
+
+      context 'with a string as input' do
+        it 'returns a valid response with a string as text input' do
+          original_length = text.length
+          response_text = rephrase.request
+
+          expect(response_text).to be_a(DeepL::Resources::Text)
+          expect(response_text.text.length).not_to eq(original_length)
+          expect(response_text.detected_source_language.upcase).to eq('EN')
+        end
+      end
+
+      context 'with an array of texts as input' do
+        let(:text) do
+          [
+            'As Gregor Samsa awoke one morning from uneasy dreams he found himself transformed.',
+            'He lay on his armour-like back, and if he lifted his head a little'
+          ]
+        end
+
+        it 'returns an array of valid text objects' do
+          response_texts = rephrase.request
+
+          expect(response_texts).to all(be_a(DeepL::Resources::Text))
+          response_texts.each_with_index do |response_text, index|
+            expect(response_text.text.length).not_to eq(text[index].length)
+            expect(response_text.detected_source_language.upcase).to eq('EN')
+          end
+        end
+      end
+    end
+
+    context 'with a writing style or tone from the provided constants applied' do
+      let(:writing_style) { DeepL::Constants::WritingStyle::BUSINESS }
+      let(:tone) { DeepL::Constants::Tone::FRIENDLY }
+
+      it 'has the correct writing style and tone applied' do
+        expect(rephrase.writing_style).to eq('business')
+        expect(rephrase.tone).to eq('friendly')
+      end
+    end
+
+    context 'with an invalid writing style applied' do
+      let(:writing_style) { 'angry' }
+
+      it 'raises a bad request error' do
+        expect { rephrase.request }.to raise_error(DeepL::Exceptions::BadRequest)
+      end
+    end
+
+    context 'when both writing style and tone are applied' do
+      let(:writing_style) { 'business' }
+      let(:tone) { 'friendly' }
+
+      it 'raises a bad request error' do
+        expect { rephrase.request }.to raise_error(DeepL::Exceptions::BadRequest)
+      end
+    end
+
+    context 'when performing a bad request' do
+      context 'when using an invalid token' do
+        let(:api) do
+          api = build_deepl_api
+          api.configuration.auth_key = 'invalid'
+          api
+        end
+
+        it 'raises an unauthorized error' do
+          expect { rephrase.request }.to raise_error(DeepL::Exceptions::AuthorizationFailed)
+        end
+      end
+    end
+  end
+end

data/spec/requests/translate_spec.rb

@@ -121,6 +121,17 @@ describe DeepL::Requests::Translate do
         request = described_class.new(api, nil, nil, nil, split_sentences: '1')
         expect(request.options[:split_sentences]).to eq('1')
       end
+
+      it 'works with provided constants' do
+        request = described_class.new(
+          api,
+          nil,
+          nil,
+          nil,
+          split_sentences: DeepL::Constants::SplitSentences::SPLIT_ON_PUNCTUATION_AND_NEWLINES
+        )
+        expect(request.options[:split_sentences]).to eq('1')
+      end
     end
 
     context 'when using `preserve_formatting` options' do
@@ -189,6 +200,12 @@ describe DeepL::Requests::Translate do
         request = described_class.new(api, nil, nil, nil, formality: 'more')
         expect(request.options[:formality]).to eq('more')
       end
+
+      it 'works with provided constants' do
+        request = described_class.new(api, nil, nil, nil,
+                                      formality: DeepL::Constants::Formality::MORE)
+        expect(request.options[:formality]).to eq('more')
+      end
     end
 
     context 'when using `model_type` options' do
@@ -201,6 +218,12 @@ describe DeepL::Requests::Translate do
         request = described_class.new(api, nil, nil, nil, model_type: 'latency_optimized')
         expect(request.options[:model_type]).to eq('latency_optimized')
       end
+
+      it 'works with provided constants' do
+        request = described_class.new(api, nil, nil, nil,
+                                      model_type: DeepL::Constants::ModelType::LATENCY_OPTIMIZED)
+        expect(request.options[:model_type]).to eq('latency_optimized')
+      end
     end
   end
 

data/spec/spec_helper.rb

@@ -57,9 +57,13 @@ 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 = {
-    # Uncomment this line when adding new tests, run the tests once, then comment it again
-    # record: :new_episodes,
+    record: record_mode,
     match_requests_on: [:method, uri_ignoring_deepl_api_subdomain, :body,
                         headers_ignoring_user_agent]
   }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: deepl-rb
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.2.0
 platform: ruby
 authors:
 - DeepL SE
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-15 00:00:00.000000000 Z
+date: 2025-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: juwelier
@@ -66,6 +66,13 @@ files:
 - lib/deepl.rb
 - lib/deepl/api.rb
 - lib/deepl/configuration.rb
+- lib/deepl/constants/base_constant.rb
+- lib/deepl/constants/formality.rb
+- lib/deepl/constants/model_type.rb
+- lib/deepl/constants/split_sentences.rb
+- lib/deepl/constants/tag_handling.rb
+- lib/deepl/constants/tone.rb
+- lib/deepl/constants/writing_style.rb
 - lib/deepl/document_api.rb
 - lib/deepl/exceptions/authorization_failed.rb
 - lib/deepl/exceptions/bad_request.rb
@@ -90,6 +97,7 @@ files:
 - lib/deepl/requests/glossary/language_pairs.rb
 - lib/deepl/requests/glossary/list.rb
 - lib/deepl/requests/languages.rb
+- lib/deepl/requests/rephrase.rb
 - lib/deepl/requests/translate.rb
 - lib/deepl/requests/usage.rb
 - lib/deepl/resources/base.rb
@@ -107,6 +115,7 @@ files:
 - spec/api/api_spec.rb
 - spec/api/configuration_spec.rb
 - spec/api/deepl_spec.rb
+- spec/constants/constants_spec.rb
 - spec/fixtures/vcr_cassettes/deepl_document.yml
 - spec/fixtures/vcr_cassettes/deepl_document_download.yml
 - spec/fixtures/vcr_cassettes/deepl_glossaries.yml
@@ -115,6 +124,7 @@ files:
 - spec/fixtures/vcr_cassettes/deepl_usage.yml
 - spec/fixtures/vcr_cassettes/glossaries.yml
 - spec/fixtures/vcr_cassettes/languages.yml
+- spec/fixtures/vcr_cassettes/rephrase_texts.yml
 - spec/fixtures/vcr_cassettes/translate_texts.yml
 - spec/fixtures/vcr_cassettes/usage.yml
 - spec/integration_tests/document_api_spec.rb
@@ -126,6 +136,7 @@ files:
 - spec/requests/glossary/language_pairs_spec.rb
 - spec/requests/glossary/list_spec.rb
 - spec/requests/languages_spec.rb
+- spec/requests/rephrase_spec.rb
 - spec/requests/translate_spec.rb
 - spec/requests/usage_spec.rb
 - spec/resources/glossary_spec.rb
@@ -157,7 +168,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Official Ruby library for the DeepL language translation API.