ai_minecraft_image

defmodule AiMinecraftImage do
  @moduledoc """
  Provides functions for generating Minecraft skin images from various sources.

  This module focuses on building URLs for Supermaker.ai's image processing service
  to create Minecraft skins. It offers functions for specifying image URLs,
  color palettes, and other skin customization options.
  """

  @base_url "https://supermaker.ai/api/minecraft/skin"

  @doc """
  Builds a URL for generating a Minecraft skin from an image URL.

  ## Examples

      iex> AiMinecraftImage.build_url("https://example.com/image.png")
      "https://supermaker.ai/api/minecraft/skin?url=https%3A%2F%2Fexample.com%2Fimage.png"

      iex> AiMinecraftImage.build_url("https://example.com/image.png", palette: "grayscale")
      "https://supermaker.ai/api/minecraft/skin?url=https%3A%2F%2Fexample.com%2Fimage.png&palette=grayscale"

      iex> AiMinecraftImage.build_url("https://example.com/image.png", palette: "grayscale", dither: true)
      "https://supermaker.ai/api/minecraft/skin?url=https%3A%2F%2Fexample.com%2Fimage.png&palette=grayscale&dither=true"

  """
  @spec build_url(String.t(), keyword()) :: String.t()
  def build_url(image_url, opts \\ []) do
    params = [url: image_url] ++ opts
    build_url_with_params(params)
  end

  @doc """
  Builds a URL with a list of parameters.

  ## Examples

      iex> AiMinecraftImage.build_url_with_params([url: "https://example.com/image.png", palette: "grayscale"])
      "https://supermaker.ai/api/minecraft/skin?url=https%3A%2F%2Fexample.com%2Fimage.png&palette=grayscale"
  """
  @spec build_url_with_params(list({atom(), any()})) :: String.t()
  def build_url_with_params(params) do
    params
    |> Enum.reject(fn {_k, v} -> is_nil(v) end)
    |> Enum.map(fn {k, v} -> "#{k}=#{URI.encode(to_string(v))}" end)
    |> Enum.join("&")
    |> then(fn query ->
      if query == "" do
        @base_url
      else
        "#{@base_url}?#{query}"
      end
    end)
  end

  @doc """
  Generates a list of available color palettes.

  ## Examples

      iex> AiMinecraftImage.available_palettes()
      [:default, :grayscale, :monochrome]
  """
  @spec available_palettes() :: list(atom())
  def available_palettes do
    [:default, :grayscale, :monochrome]
  end

  @doc """
  Converts a color palette atom to its string representation.

  ## Examples

      iex> AiMinecraftImage.palette_to_string(:grayscale)
      "grayscale"

      iex> AiMinecraftImage.palette_to_string(:default)
      "default"
  """
  @spec palette_to_string(atom()) :: String.t()
  def palette_to_string(palette) when is_atom(palette) do
    Atom.to_string(palette)
  end

  @doc """
  Validates if a given palette is in the list of available palettes.

  ## Examples

      iex> AiMinecraftImage.valid_palette?(:grayscale)
      true

      iex> AiMinecraftImage.valid_palette?(:rainbow)
      false
  """
  @spec valid_palette?(atom()) :: boolean()
  def valid_palette?(palette) when is_atom(palette) do
    palette in available_palettes()
  end
end