defmodule Soap do
  @moduledoc """
  The SOAP client for Elixir based on `HTTPoison` (for send requests) and `SweetXml` (for XML parsing).

  Soap contains 5 main modules:

    * `Soap.Wsdl` - Build wsdl components data map. Can parse raw wsdl file
      from external url or local path. Wsdl which is prepared this module are
      using for send requests.

    * `Soap.Request` - Provides functionality for build and calling requests.
      Contains Request.Headers and Soap.Params submodules for build headers and
      build body with parameters validation respectively.  This module is a
      wrapper over HTTPoison. It send requests and handle them.

    * `Soap.Response` - Handle soap response and handle them. It provides
      functionality for parsing xml-like body and transform it to comfortable
      structure. Structure for this module returns with necessary data after send
      a request.

    * `Soap.Xsd` - This module have same functionality as Soap.Wsdl module, but
      only for Xsd-files. It allows to parse xsd files from external resources or
      local path and convert it to map.

    * `Soap.Type` - Provides a functionality for find and parse complex types
      from raw xsd file. It uses in library for validation parameters when we
      build request body.

  The `Soap` module can be used to parse WSDL files:

  ```elixir
  iex> Soap.init_model("https://git.io/vNCWd", :url)
  {:ok, %{
    complex_types: [...],
    endpoint: "...",
    messages: [...],
    namespaces: %{...},
    operations: [...],
    schema_attributes: %{...},
    soap_version: "x.x",
    validation_types: %{...}
    }
  }
  ```

  And send requests:

  ```elixir
  iex> Soap.call(wsdl, action, params)
  {:ok, %Soap.Response{}}
  ```

  It's very common to use Soap in order to wrap APIs.
  See `call/5` for more details on how to issue requests to soap services
  """

  alias Soap.{Request, Response, Wsdl}

  @doc """
  Initialization of a WSDL model. Response a map of parsed data from file.
  Returns `{:ok, wsdl}`.

  ## Parameters

  - `path`: Path for wsdl file.
  - `type`: Atom that represents the type of path for WSDL file. Can be `:file`
    or `url`. Default: `:file`.
  - `endpoint`: Endpoint to be used for the request.  Defaults to the endpoint
    specified in the WSDL file.  Useful for (e.g.) sending a request to a mock
    server during testing.
  - `opts`: any options for `HTTPoison.Request` and the following parsing options:

    * `:soap_version` - Specifies SOAP version for parsing.
    * `:allow_empty_soap_actions` - Allows SOAP operations with an empty
      `soapAction` attribute. This may be required for APIs that do not set a
      `soapAction` for each operation.
    * `:skip_type_imports` - Prevents fetching external XSDs for importing types.

  ## Examples

      iex> {:ok, wsdl} = Soap.init_model("https://git.io/vNCWd", :url)
      {:ok, %{...}}

  """
  @spec init_model(String.t(), :file | :url, list()) :: {:ok, map()}
  def init_model(path, type \\ :file, opts \\ [])
  def init_model(path, :file, opts), do: Wsdl.parse_from_file(path, opts)
  def init_model(path, :url, opts), do: Wsdl.parse_from_url(path, opts)

  @doc """
  Send a request to the SOAP server based on the passed WSDL file, action and parameters.

  Returns `{:ok, %Soap.Response{}}` if the request is successful, `{:error, reason}` otherwise.

  ## Parameters

  - `wsdl`: Wsdl model from `Soap.init_model/2` function.
  - `action`: Soap action to be called. Use `Soap.operations/1` to get a list of available actions
  - `params`: Parameters to build the body of a SOAP request.
  - `headers`: Custom request headers.
  - `opts`: HTTPoison options.

  ## Examples

      iex> Soap.call(wsdl, action, params)
      {:ok, %Soap.Response{}}

  """
  @spec call(wsdl :: map(), operation :: String.t(), params :: map(), headers :: any(), opts :: any()) :: any()
  def call(wsdl, operation, params, headers \\ [], opts \\ []) do
    wsdl
    |> validate_operation(operation)
    |> Request.call(operation, params, headers, opts)
    |> handle_response
  end

  @doc """
  Returns a list of available actions of the passed WSDL.

  ## Parameters

  - `wsdl`: Wsdl model from `Soap.init_model/2` function.

  ## Examples

      iex> {:ok, wsdl} = Soap.init_model("https://git.io/vNCWd", :url)
      iex> Soap.operations(wsdl)
      ["SendMessage", "SendMessageMultipleRecipients"]

  """
  @spec operations(map()) :: nonempty_list(String.t())
  def operations(wsdl) do
    wsdl.operations
  end

  defp handle_response(
         {:ok, %HTTPoison.Response{body: body, headers: headers, request_url: request_url, status_code: status_code}}
       ) do
    {:ok, %Response{body: body, headers: headers, request_url: request_url, status_code: status_code}}
  end

  defp handle_response({:error, %HTTPoison.Error{reason: reason}}) do
    {:error, reason}
  end

  defp validate_operation(wsdl, operation) do
    case valid_operation?(wsdl, operation) do
      false -> raise OperationError, operation
      true -> wsdl
    end
  end

  defp valid_operation?(wsdl, operation) do
    Enum.any?(wsdl[:operations], &(&1[:name] == operation))
  end
end
