defmodule LoopsEx.Events do
  @moduledoc """
  Trigger email sending with events.
  """

  alias LoopsEx.Client

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

  @doc """
  Send an event to trigger emails via Loops.

  ## Parameters

    - `params` (map): must include:
      - `email` or `userId` to identify the contact.
      - `eventName` (string): the name of the event.
      - Optional `eventProperties` (map): event-specific data.
      - Optional `mailingLists` (map): mailing list subscriptions.

  ## Returns

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

  ## Example

      iex> LoopsEx.Events.send_event(%{
      "email" => "john@example.com",
      "eventName" => "signup",
      "eventProperties" => %{"plan" => "Pro"}
      })
      {:ok, %{"success" => true}}
  """
  @spec send_event(map()) :: response()
  def send_event(params) when is_map(params) do
    Client.request_api(:post, "/events/send", params)
    |> Client.handle_response()
  end
end