defmodule LoopsEx.Contacts do
  @moduledoc """
  Manage contacts in your audience.
  """
  @typedoc "Response type returned by Loops API calls"
  @type response :: LoopsEx.Client.response()

  alias LoopsEx.Client

  @doc """
  Create or upsert a contact in your Loops audience.

  ## Parameters

    - `params` (map): contact data. Must include `"email"` or `"userId"`. Optional fields: `"firstName"`, `"lastName"`, custom properties.

  ## Returns

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

  ## Example

      iex> LoopsEx.Contacts.create(%{"email" => "john@example.com", "firstName" => "John"})
      {:ok, %{"success" => true, "id" => "contact_id"}}
  """
  @spec create(map()) :: response()
  def create(params) when is_map(params) do
    Client.request_api(:post, "/contacts/create", params)
    |> Client.handle_response()
  end

  @doc """
  Update an existing contact by `"email"` or `"userId"`.

  ## Parameters

    - `params` (map): fields to update. Must include `"email"` or `"userId"`.

  ## Returns

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

  ## Example

      iex> LoopsEx.Contacts.update(%{"email" => "john@example.com", "firstName" => "Jane"})
      {:ok, %{"success" => true, "id" => "contact_id"}}
  """
  @spec update(map()) :: response()
  def update(params) when is_map(params) do
    Client.request_api(:put, "/contacts/update", params)
    |> Client.handle_response()
  end

  @doc """
  Find contacts by `"email"` or `"userId"`.

  ## Parameters

    - `params` (map): query params. Provide `"email"` or `"userId"`.

  ## Returns

    - `{:ok, [contact_maps]}` on success.
    - `{:error, {status_code, response_body}}` on failure.

  ## Example

      iex> LoopsEx.Contacts.find(%{"email" => "john@example.com"})
      {:ok, [%{"email" => "john@example.com", ...}]}
  """
  @spec find(map()) :: response()
  def find(params) when is_map(params) do
    Client.request_api(:get, "/contacts/find", %{}, params)
    |> Client.handle_response()
  end

  @doc """
  Delete a contact by `"email"` or `"userId"`.

  ## Parameters

    - `params` (map): provide only one of `"email"` or `"userId"`.

  ## Returns

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

  ## Example

      iex> LoopsEx.Contacts.delete(%{"userId" => "user_123"})
      {:ok, %{"success" => true, "message" => "Contact deleted."}}
  """
  @spec delete(map()) :: response()
  def delete(params) when is_map(params) do
    Client.request_api(:post, "/contacts/delete", params)
    |> Client.handle_response()
  end
end