defmodule CampaignFlow.Client.Users do
  @moduledoc """
  User resource operations for the Campaign Flow API.
  """

  alias CampaignFlow.Client
  alias CampaignFlow.Client.Request

  @doc """
  Lists all users.

  ## Options

    * `:page` - Page number for pagination
    * `:per_page` - Number of items per page

  ## Examples

      {:ok, users} = CampaignFlow.Client.Users.list(client)
      {:ok, users} = CampaignFlow.Client.Users.list(client, page: 2)
  """
  @spec list(Client.t(), keyword()) :: Client.Request.response()
  def list(client, params \\ []) do
    Request.get(client, "/users", params: params)
  end

  @doc """
  Retrieves a specific user by ID.

  ## Examples

      {:ok, user} = CampaignFlow.Client.Users.get(client, 123)
  """
  @spec get(Client.t(), integer()) :: Client.Request.response()
  def get(client, id) do
    Request.get(client, "/users/#{id}")
  end

  @doc """
  Creates a new user.

  ## Examples

      {:ok, user} = CampaignFlow.Client.Users.create(client, %{
        email: "user@example.com",
        name: "John Doe"
      })
  """
  @spec create(Client.t(), map()) :: Client.Request.response()
  def create(client, params) do
    Request.post(client, "/users", json: params)
  end

  @doc """
  Updates an existing user.

  ## Examples

      {:ok, user} = CampaignFlow.Client.Users.update(client, 123, %{
        name: "Jane Doe"
      })
  """
  @spec update(Client.t(), integer(), map()) :: Client.Request.response()
  def update(client, id, params) do
    Request.put(client, "/users/#{id}", json: params)
  end
end