defmodule LoopsEx.TransactionalEmails do
  @moduledoc """
  Send and list transactional emails.
  """

  alias LoopsEx.Client

  @typedoc "Response type returned by Loops API calls"
  @type response :: LoopsEx.Client.response()

  @doc """
  Send a transactional email to a contact.

  ## Parameters

    - `params` (map): must include:
      - `"email"` (string): recipient email address.
      - `"transactionalId"` (string): ID of the transactional template.
      - Optional `"addToAudience"` (boolean).
      - Optional `"dataVariables"` (map) for template variables.
      - Optional `"attachments"` (list of maps) with keys `"filename"`, `"contentType"`, `"data"`.

  ## Returns

    - `{:ok, %{"success" => true}}` on success.
    - `{:error, {status_code, response_body}}` on HTTP error.

  ## Example

      iex> LoopsEx.TransactionalEmails.send_transactional(%{
      ...>   "email" => "john@example.com",
      ...>   "transactionalId" => "tid123",
      ...>   "dataVariables" => %{"name" => "John"}
      ...> })
      {:ok, %{"success" => true}}
  """
  @spec send_transactional(map()) :: response()
  def send_transactional(params) when is_map(params) do
    Client.request_api(:post, "/transactional", params)
    |> Client.handle_response()
  end

  @doc """
  List published transactional email templates.

  ## Parameters

    - `params` (map): optional query params:
      - `"perPage"` (string): number of items per page (10-50).
      - `"cursor"` (string): pagination cursor.

  ## Returns

    - `{:ok, [map()]}` list of templates on success.
    - `{:error, {status_code, response_body}}` on HTTP error.

  ## Example

      iex> LoopsEx.TransactionalEmails.list(%{"perPage" => "20"})
      {:ok, [%{"id" => "tid123", "name" => "Welcome", "lastUpdated" => "...", "dataVariables" => ["name"]}, ...]}
  """
  @spec list(map()) :: response()
  def list(params \\ %{}) do
    Client.request_api(:get, "/transactional", %{}, params)
    |> Client.handle_response()
  end
end