Update Package Version & Modules Documentation (#10)

New Features

- Introduced text rephrasing functionality for Pro users, including options for writing style and tone.
- Added new modules for translation and rephrasing with improved APIs.

Documentation

- Expanded and clarified module and function documentation, including detailed usage examples and option descriptions.
- Updated README and getting started guides for conciseness, improved formatting, and new badges.
- Enhanced changelog with detailed entries for version 0.2.0.

Bug Fixes

- Resolved a compilation error related to API key configuration.

Tests

- Updated and added tests for translation, rephrasing, and usage features to match new API changes.

Chores

- Bumped project version to 0.2.0

Author: muzhawir

README.md

@@ -30,11 +30,10 @@ To install `deepl`, follow the instructions in the
 
 ## Usage
 
-Complete usage examples can be found in each module's documentation. See the
-[API Reference](https://hexdocs.pm/deepl/api-reference.html) page. Below are some basic examples
-to get you started.
+See the [API Reference](https://hexdocs.pm/deepl/api-reference.html) for full examples.
+Here are some basics:
 
-Translate a text:
+**Translate text:**
 
 ```elixir
 iex> Deepl.Translator.translate("Hello World", "ID")
@@ -46,7 +45,7 @@ iex> Deepl.Translator.translate("Hello World", "ID")
  }}
 ```
 
-Rephrase a text:
+**Rephrase text:**
 
 ```elixir
 iex> Deepl.Writer.rephrase("this is a example sentence to imprve", "en-US")
@@ -62,7 +61,7 @@ iex> Deepl.Writer.rephrase("this is a example sentence to imprve", "en-US")
  }}
 ```
 
-Retrieve usage and quota information:
+**Get usage and quota:**
 
 ```elixir
 iex> Deepl.Usage.get()

lib/deepl.ex

@@ -1,13 +1,11 @@
 defmodule Deepl do
   @moduledoc """
-  An Elixir package providing a convenient interface to the [DeepL](https://www.deepl.com) API.
+  Provide base functions for the DeepL API.
   """
   @moduledoc since: "0.1.0"
 
   @doc """
-  Get the API key from the application environment.
-
-  Retrieves the API key set in the application configuration.
+  Get the currently active API key.
 
   ## Examples
 
@@ -19,9 +17,7 @@ defmodule Deepl do
   def get_api_key, do: Application.get_env(:deepl, :api_key) || nil
 
   @doc """
-  Sets the API key for the DeepL service.
-
-  Stores the API key string in the application environment.
+  Set the API key in the application environment.
 
   ## Examples
 
@@ -33,9 +29,9 @@ defmodule Deepl do
   def set_api_key(key), do: Application.put_env(:deepl, :api_key, key)
 
   @doc """
-  Gets the current plan of the DeepL API based on the API key.
+  Get current plan based on the API key.
 
-  Returns `:free` for free accounts and `:pro` for pro accounts.
+  Returns atom `:free` for free accounts and `:pro` for pro accounts.
 
   ## Examples
 
@@ -51,10 +47,10 @@ defmodule Deepl do
   end
 
   @doc """
-  Get the base URL for the DeepL API based on the current plan.
+  Get base URL based on API key input.
 
-  Returns the base URL for the DeepL API, which varies depending on whether the user has a
-  free or pro plan.
+  Returns base URL for pro or free accounts, determined by the API key, free account keys end
+  with `:fx`.
 
   ## Examples
 

lib/deepl/http_helper.ex

@@ -3,18 +3,19 @@ defmodule Deepl.HTTPHelper do
   @moduledoc since: "0.1.0"
 
   @doc """
-  Returns the required headers for Deepl API requests.
+  Returns the required headers for a DeepL API request.
   """
-  @spec required_request_header(Keyword.t()) :: list(tuple())
-  def required_request_header(opts \\ []) do
+  @spec required_request_headers(Keyword.t()) :: list(tuple())
+  def required_request_headers(opts \\ []) do
     [
       {"Accept", Keyword.get(opts, :accept, "application/json")},
-      {"Authorization", "DeepL-Auth-Key " <> Deepl.get_api_key()}
+      {"Authorization", "DeepL-Auth-Key " <> Deepl.get_api_key()},
+      {"Content-Type", Keyword.get(opts, :content_type, "application/json")}
     ]
   end
 
   @doc """
-  Filters a keyword list to only include keys that are present in the given struct.
+  Filters keywords by the keys of a given struct.
 
   This function ensures that only valid options for the struct are included in the final map
   before sending a request to the DeepL API.
@@ -48,8 +49,8 @@ defmodule Deepl.HTTPHelper do
   @doc """
   Handles the response from the DeepL API.
 
-  It decodes the JSON body and returns the decoded body on success, or raises an exception on
-  error.
+  This function behaves like `response/2`, but raises an exception if the response is not
+  successful.
   """
   @spec response!(non_neg_integer(), binary()) :: map() | Exception.t()
   def response!(status, body) do

lib/deepl/request.ex

@@ -4,6 +4,12 @@ defmodule Deepl.Request do
 
   @callback run_request(term()) :: {term(), Req.Response.t() | Exception.t()}
 
+  @doc """
+  Runs the request using the configured request behaviour.
+
+  This function is used internally by the library to execute HTTP requests.
+  """
+  @spec run_request(term()) :: {term(), Req.Response.t() | Exception.t()}
   def run_request(request), do: implement().run_request(request)
 
   defp implement, do: Application.get_env(:deepl, :request_behaviour, Req.Request)

lib/deepl/translator.ex

@@ -1,6 +1,11 @@
 defmodule Deepl.Translator do
   @moduledoc """
-  Translates the given text to the target language.
+  Provides functions to translate text.
+
+  API references for this module can be found in the Translate text
+  [documentation](https://developers.deepl.com/api-reference/translate), please
+  refer to the documentation for more information, especially options parameters detail usage in
+  `translate/3` or `translate!/3`.
   """
   @moduledoc since: "0.1.0"
 
@@ -10,9 +15,56 @@ defmodule Deepl.Translator do
   @type text :: binary() | list(binary())
 
   @doc """
-  Translates a single or multiple texts to the specified target language.
+  Translates the given text to the specified target language.
+
+  The `text` parameter can be a single string or a list of strings, and the `target_lang`
+  parameter specifies the language the text should be translated to, available languages can be
+  found in the translation target languages
+  [documentation](https://developers.deepl.com/docs/getting-started/supported-languages#translation-target-languages).
+
+  ## Options
+
+  The accepted options are:
+
+  - `context` - Add additional context that can influence a translation but is not translated
+    itself, the value must be a string.
+  - `model_type` - Specifies which DeepL model should be used for translation, the value must be
+    a string.
+  - `split_sentences` - Sets whether the translation engine should first split the input into
+    sentences, the value must be a string.
+  - `preserve_formatting` - Sets whether the translation engine should respect the original
+    formatting, even if it would usually correct some aspects, the value must be a boolean.
+  - `formality` - Sets whether the translated text should lean towards formal or informal
+    language, the value must be a string.
+  - `glossary_id` - Specify the glossary to use for the translation, this option requires the
+    `source_lang` option to be set, the value must be a string.
+  - `show_billed_characters` - Show the number of billed characters in the response, the value
+    must be a boolean.
+  - `tag_handling` - Sets which kind of tags should be handled, the value must be a string.
+  - `outline_detection` - Set the automatic detection of XML structure, the value must be a
+    boolean.
+  - `non_splitting_tags` - Set the XML tags that should not be split, the value must be a list of
+    strings.
+  - `splitting_tags` - Set the XML tags that always cause splits, the value must be a list of
+    strings.
+  - `ignore_tags` - Set the XML tags that you do not want to be translated, the value must be a
+    list of strings.
+
+  The values for `model_type` can be:
+
+  - `latency_optimized`, `quality_optimized`, `prefer_quality_optimized`
+
+  The value for `split_sentences` can be:
+
+  - `"0"`, `"1"`, `"nonewlines"`
+
+  The values for `formality` can be:
+
+  - `default`, `more`, `less`, `prefer_more`, `prefer_less`
+
+  The values for `tag_handling` can be:
 
-  The `text` parameter can be a single string or a list of strings.
+  - `xml` or `html`
 
   ## Examples
 
@@ -24,9 +76,7 @@ defmodule Deepl.Translator do
          ]
        }}
 
-      iex> Deepl.Translator.translate(
-      ...>  ["Hello World", "Hello Developer"], "ID", show_billed_characters: true
-      ...> )
+      iex> Deepl.Translator.translate(["Hello World", "Hello Developer"], "ID", show_billed_characters: true)
       {:ok,
        %{
          "translations" => [

lib/deepl/translator/translate_request.ex

@@ -2,7 +2,7 @@ defmodule Deepl.Translator.TranslateRequest do
   @moduledoc false
   @moduledoc since: "0.1.0"
 
-  import Deepl.HTTPHelper, only: [required_request_header: 0]
+  import Deepl.HTTPHelper, only: [required_request_headers: 0]
 
   alias Deepl.HTTPHelper
   alias Req.Request
@@ -44,7 +44,7 @@ defmodule Deepl.Translator.TranslateRequest do
       [
         method: :post,
         url: Deepl.base_url!() <> "/v2/translate",
-        headers: [{"Content-Type", "application/json"} | required_request_header()],
+        headers: required_request_headers(),
         body: body
       ]
       |> Request.new()

lib/deepl/usage.ex

@@ -1,18 +1,21 @@
 defmodule Deepl.Usage do
   @moduledoc """
-  Module for retrieving usage and quota for the current billing period with the DeepL API.
+  Provides function to retrieve usage and quota information.
 
-  For more information, refer to the retrieve usage and quota
+  API references for this module can be found in the Retrieve usage & quota
   [documentation](https://developers.deepl.com/api-reference/usage-and-quota).
   """
   @moduledoc since: "0.0.1"
 
-  import Deepl.HTTPHelper, only: [required_request_header: 0, response: 2]
+  import Deepl.HTTPHelper, only: [required_request_headers: 0, response: 2]
 
   alias Req.Request
 
   @doc """
-  Retrieve current usage and quota information.
+  Get the usage and quota information for current API key.
+
+  Returns usage and quota information, the output depends on the type of API key used
+  (Free or Pro).
 
   ## Examples
 
@@ -55,7 +58,7 @@ defmodule Deepl.Usage do
       [
         method: :get,
         url: Deepl.base_url!() <> "/v2/usage",
-        headers: required_request_header()
+        headers: required_request_headers()
       ]
       |> Request.new()
       |> Deepl.Request.run_request()

lib/deepl/writer.ex

@@ -1,13 +1,16 @@
 defmodule Deepl.Writer do
   @moduledoc """
+  Provides functions to rephrase text.
+
+  API references for this module can be found in the
+  [Improve text documentation](https://developers.deepl.com/api-reference/improve-text).
+
   > #### DeepL API Pro Subscription {: .info}
   >
-  > **DeepL API for Write** requires a Pro subscription, ensure you use Pro API key for using
-  > functions in this module.
-
-  Provides functions to rephrase text.
+  > **DeepL API for Write** requires a Pro subscription. Ensure you use a Pro API key to access
+  > the functions in this module.
   """
-  @moduledoc since: "0.1.3"
+  @moduledoc since: "0.2.0"
 
   alias Deepl.HTTPHelper
   alias Deepl.Writer.RephraseRequest
@@ -17,7 +20,31 @@ defmodule Deepl.Writer do
   @doc """
   Rephrases the given text to the target language.
 
-  The `text` parameter can be a single string or a list of strings.
+  The `text` parameter can be a single string or a list of strings, and the `target_lang`
+  parameter available languages can be found in the Improve text
+  [documentation](https://developers.deepl.com/api-reference/improve-text#param-target-lang).
+
+  ## Options
+
+  The accepted options are:
+
+  - `writing_style` - Changes the writing style of your improvements, the value must be a string.
+  - `tone` - Changes the tone of your improvements, the value must be a string.
+
+  > #### Using `writing_style` and `tone` {: .error}
+  >
+  > It’s not possible to include both `writing_style` and `tone` in a request; only one or the
+  > other can be included, if you include both, the response will be an error.
+
+  The values for `writing_style` can be:
+
+  - `simple`, `business`, `academic`, `casual`, `default`, `prefer_simple`, `prefer_business`,
+    `prefer_academic`, `prefer_casual`.
+
+  The values for `tone` can be:
+
+  - `friendly`, `enthusiastic`, `confident`, `diplomatic`, `default`, `prefer_enthusiastic`,
+    `prefer_friendly`, `prefer_confident`, `prefer_diplomatic`.
 
   ## Examples
 
@@ -57,9 +84,13 @@ defmodule Deepl.Writer do
   """
   @spec rephrase(text(), String.t(), Keyword.t()) :: {:ok, map()} | {:error, String.t()}
   def rephrase(text, target_lang, opts \\ []) when is_binary(text) or is_list(text) do
-    response = RephraseRequest.post_rephrase(text, target_lang, opts)
+    if Keyword.has_key?(opts, :tone) && Keyword.has_key?(opts, :writing_style) do
+      {:error, "Cannot include both tone and writing_style options"}
+    else
+      response = RephraseRequest.post_rephrase(text, target_lang, opts)
 
-    HTTPHelper.response(response.status, response.body)
+      HTTPHelper.response(response.status, response.body)
+    end
   end
 
   @doc """
@@ -69,8 +100,12 @@ defmodule Deepl.Writer do
   """
   @spec rephrase!(text(), String.t(), Keyword.t()) :: map()
   def rephrase!(text, target_lang, opts \\ []) when is_binary(text) or is_list(text) do
-    response = RephraseRequest.post_rephrase(text, target_lang, opts)
+    if Keyword.has_key?(opts, :tone) && Keyword.has_key?(opts, :writing_style) do
+      raise ArgumentError, "Cannot include both tone and writing_style options"
+    else
+      response = RephraseRequest.post_rephrase(text, target_lang, opts)
 
-    HTTPHelper.response!(response.status, response.body)
+      HTTPHelper.response!(response.status, response.body)
+    end
   end
 end

lib/deepl/writer/rephrase_request.ex

@@ -2,7 +2,7 @@ defmodule Deepl.Writer.RephraseRequest do
   @moduledoc false
   @moduledoc since: "0.1.3"
 
-  import Deepl.HTTPHelper, only: [required_request_header: 0]
+  import Deepl.HTTPHelper, only: [required_request_headers: 0]
 
   alias Deepl.HTTPHelper
   alias Req.Request
@@ -11,6 +11,11 @@ defmodule Deepl.Writer.RephraseRequest do
 
   defstruct text: nil, target_lang: nil, writing_style: nil, tone: nil
 
+  @doc """
+  Sends a rephrasing request to the DeepL API.
+
+  Constructs a request to rephrase the provided text in the specified target language.
+  """
   @spec post_rephrase(text(), String.t(), Keyword.t()) :: Req.Response.t() | Exception.t()
   def post_rephrase(text, target_lang, opts \\ []) do
     body =
@@ -25,7 +30,7 @@ defmodule Deepl.Writer.RephraseRequest do
       [
         method: :post,
         url: Deepl.base_url!() <> "/v2/write/rephrase",
-        headers: [{"Content-Type", "application/json"} | required_request_header()],
+        headers: required_request_headers(),
         body: body
       ]
       |> Request.new()