podcast_rss

defmodule PodcastRSS do
  @moduledoc """
  A library for generating podcast RSS feeds.

  PodcastRSS provides a simple, pipeline-friendly API for creating RSS 2.0 feeds
  suitable for podcast distribution. It focuses on simplicity and readability
  while supporting the core requirements for podcast feeds.

  ## Examples

      alias PodcastRSS.Episode

      channel = PodcastRSS.new()
        |> PodcastRSS.title("Retro Gaming Chronicles")
        |> PodcastRSS.link("https://example.com")
        |> PodcastRSS.description("Exploring the golden age of video games")
        |> PodcastRSS.self_link("https://feeds.example.com/rss")
        |> PodcastRSS.image("https://example.com/cover.png")
        |> PodcastRSS.language("en-us")

      episode = channel
        |> PodcastRSS.new_episode()
        |> Episode.title("The Birth of the NES")
        |> Episode.description("How Nintendo revolutionized home gaming in 1985")
        |> Episode.enclosure("https://example.com/episodes/nes-birth.mp3", 45678901, "audio/mpeg")
        |> Episode.guid("retro-001-nes-birth")
        |> Episode.duration("01:23:45")

      feed_xml = channel
        |> PodcastRSS.add_episode(episode)
        |> PodcastRSS.to_xml()

  """

  alias PodcastRSS.Channel
  alias PodcastRSS.XML

  @doc """
  Create a new channel with useful defaults.

  Pre-registers common podcast namespaces:
  - iTunes namespace for iTunes-specific tags
  - Podcast Index namespace for modern podcast features
  - Atom namespace for RSS 2.0 compliance
  - PSC (Podlove Simple Chapters) namespace for chapter support

  Sets default values:
  - Language: "en-us"
  - iTunes block: "No"
  - iTunes complete: "No"

  For a completely empty channel without any defaults, use `PodcastRSS.Channel.new/0`.
  """
  @spec new() :: Channel.t()
  def new() do
    Channel.new()
    |> register_namespace("atom", "http://www.w3.org/2005/Atom")
    |> register_namespace("itunes", "http://www.itunes.com/dtds/podcast-1.0.dtd")
    |> register_namespace("podcast", "https://podcastindex.org/namespace/1.0")
    |> register_namespace("psc", "http://podlove.org/simple-chapters")
    |> language("en-us")
    |> custom_field("itunes:block", "No")
    |> custom_field("itunes:complete", "No")
  end

  # Delegate channel functions to Channel module with enhanced documentation

  @doc """
  Set the channel title.

  Delegates to `PodcastRSS.Channel.title/2`.
  """
  defdelegate title(channel, title), to: Channel

  @doc """
  Set the channel link (website URL).

  Delegates to `PodcastRSS.Channel.link/2`.
  """
  defdelegate link(channel, link), to: Channel

  @doc """
  Set the canonical RSS feed URL.

  Delegates to `PodcastRSS.Channel.self_link/2`.
  """
  defdelegate self_link(channel, feed_url), to: Channel

  @doc """
  Set the podcast cover image URL.

  Delegates to `PodcastRSS.Channel.image/2`.
  """
  defdelegate image(channel, image_url), to: Channel

  @doc """
  Set the podcast language.

  Delegates to `PodcastRSS.Channel.language/2`.
  """
  defdelegate language(channel, language_code), to: Channel

  @doc """
  Set the podcast category.

  Delegates to `PodcastRSS.Channel.category/2`.
  """
  defdelegate category(channel, category), to: Channel

  @doc """
  Set the podcast category with subcategory.

  Delegates to `PodcastRSS.Channel.category/3`.
  """
  defdelegate category(channel, category, subcategory), to: Channel

  @doc """
  Set the channel description.

  Delegates to `PodcastRSS.Channel.description/2`.
  """
  defdelegate description(channel, description), to: Channel

  @doc """
  Create a new episode that inherits the channel's namespaces.

  Delegates to `PodcastRSS.Channel.new_episode/1`.
  """
  defdelegate new_episode(channel), to: Channel

  @doc """
  Add an episode to the channel.

  Delegates to `PodcastRSS.Channel.add_episode/2`.
  """
  defdelegate add_episode(channel, episode), to: Channel

  @doc """
  Register a namespace for use in custom fields.

  Delegates to `PodcastRSS.Channel.register_namespace/3`.
  """
  defdelegate register_namespace(channel, namespace, uri), to: Channel

  @doc """
  Add a custom field to the channel.

  Delegates to `PodcastRSS.Channel.custom_field/4`.
  """
  defdelegate custom_field(channel, name, content, opts \\ []), to: Channel

  @doc """
  Set the podcast type to episodic.

  Delegates to `PodcastRSS.Channel.type/2`.
  """
  @spec episodic(Channel.t()) :: Channel.t()
  def episodic(channel), do: Channel.type(channel, :episodic)

  @doc """
  Set the podcast type to serial.

  Delegates to `PodcastRSS.Channel.type/2`.
  """
  @spec serial(Channel.t()) :: Channel.t()
  def serial(channel), do: Channel.type(channel, :serial)

  @doc """
  Convert the channel to RSS XML string.

  Delegates to `PodcastRSS.XML.to_xml/1`.
  """
  defdelegate to_xml(channel), to: XML
end