feat: Add Audiences, Contacts, and Broadcasts API support

lib/resend/audiences.ex

@@ -0,0 +1,117 @@
+defmodule Resend.Audiences do
+  @moduledoc """
+  Manage audiences in Resend.
+
+  Audiences are groups of contacts that you can send broadcasts to. This module
+  provides functions to create, list, retrieve, and delete audiences.
+
+  ## Examples
+
+      # Create a new audience
+      {:ok, audience} = Resend.Audiences.create(name: "Newsletter Subscribers")
+
+      # List all audiences
+      {:ok, audiences} = Resend.Audiences.list()
+
+      # Get a specific audience
+      {:ok, audience} = Resend.Audiences.get("78261eea-8f8b-4381-83c6-79fa7120f1cf")
+
+      # Remove an audience
+      {:ok, removed_audience} = Resend.Audiences.remove("78261eea-8f8b-4381-83c6-79fa7120f1cf")
+  """
+
+  alias Resend.Audiences.Audience
+
+  @doc """
+  Creates a new audience.
+
+  ## Parameters
+
+    * `:name` - The name of the audience you want to create (required)
+
+  ## Examples
+
+      iex> Resend.Audiences.create(name: "Newsletter Subscribers")
+      {:ok, %Resend.Audiences.Audience{id: "78261eea-8f8b-4381-83c6-79fa7120f1cf", name: "Newsletter Subscribers"}}
+
+      iex> Resend.Audiences.create(name: "")
+      {:error, %Resend.Error{message: "Audience name is required"}}
+
+  """
+  @spec create(Keyword.t()) :: Resend.Client.response(Audience.t())
+  @spec create(Resend.Client.t(), Keyword.t()) :: Resend.Client.response(Audience.t())
+  def create(client \\ Resend.client(), opts) do
+    Resend.Client.post(client, Audience, "/audiences", %{
+      name: opts[:name]
+    })
+  end
+
+  @doc """
+  Lists all audiences in your account.
+
+  ## Examples
+
+      iex> Resend.Audiences.list()
+      {:ok, %Resend.List{data: [%Resend.Audiences.Audience{id: "78261eea-8f8b-4381-83c6-79fa7120f1cf", name: "Newsletter Subscribers"}]}}
+
+  """
+  @spec list() :: Resend.Client.response(Resend.List.t(Audience.t()))
+  @spec list(Resend.Client.t()) :: Resend.Client.response(Resend.List.t(Audience.t()))
+  def list(client \\ Resend.client()) do
+    Resend.Client.get(client, Resend.List.of(Audience), "/audiences")
+  end
+
+  @doc """
+  Gets details of a specific audience by its ID.
+
+  ## Parameters
+
+    * `audience_id` - The Audience ID (required)
+
+  ## Examples
+
+      iex> Resend.Audiences.get("78261eea-8f8b-4381-83c6-79fa7120f1cf")
+      {:ok, %Resend.Audiences.Audience{id: "78261eea-8f8b-4381-83c6-79fa7120f1cf", name: "Newsletter Subscribers"}}
+
+      iex> Resend.Audiences.get("non-existent-id")
+      {:error, %Resend.Error{message: "Audience not found"}}
+
+  """
+  @spec get(String.t()) :: Resend.Client.response(Audience.t())
+  @spec get(Resend.Client.t(), String.t()) :: Resend.Client.response(Audience.t())
+  def get(client \\ Resend.client(), audience_id) do
+    Resend.Client.get(client, Audience, "/audiences/:id",
+      opts: [
+        path_params: [id: audience_id]
+      ]
+    )
+  end
+
+  @doc """
+  Removes an audience permanently. This action cannot be undone.
+
+  Deleting an audience will also delete all associated contacts.
+
+  ## Parameters
+
+    * `audience_id` - The Audience ID (required)
+
+  ## Examples
+
+      iex> Resend.Audiences.remove("78261eea-8f8b-4381-83c6-79fa7120f1cf")
+      {:ok, %Resend.Audiences.Audience{id: "78261eea-8f8b-4381-83c6-79fa7120f1cf", deleted: true}}
+
+      iex> Resend.Audiences.remove("non-existent-id")
+      {:error, %Resend.Error{message: "Audience not found"}}
+
+  """
+  @spec remove(String.t()) :: Resend.Client.response(Audience.t())
+  @spec remove(Resend.Client.t(), String.t()) :: Resend.Client.response(Audience.t())
+  def remove(client \\ Resend.client(), audience_id) do
+    Resend.Client.delete(client, Audience, "/audiences/:id", %{},
+      opts: [
+        path_params: [id: audience_id]
+      ]
+    )
+  end
+end

lib/resend/audiences/audience.ex

@@ -0,0 +1,44 @@
+defmodule Resend.Audiences.Audience do
+  @moduledoc """
+  Resend Audience struct.
+
+  Represents an audience, which is a group of contacts that you can send broadcasts to.
+  Each audience has a unique ID that is used to reference it in other API calls.
+  """
+
+  alias Resend.Util
+
+  @behaviour Resend.Castable
+
+  @type t() :: %__MODULE__{
+          id: String.t(),
+          name: String.t() | nil,
+          created_at: DateTime.t() | nil,
+          deleted: boolean() | nil
+        }
+
+  @enforce_keys [:id]
+  defstruct [
+    :id,
+    :name,
+    :created_at,
+    :deleted
+  ]
+
+  @doc """
+  Casts a raw map from the API response into an Audience struct.
+
+  This function is used internally by the Castable protocol to convert
+  JSON responses from the Resend API into properly typed Elixir structs.
+  """
+  @impl true
+  @spec cast(map()) :: t()
+  def cast(map) do
+    %__MODULE__{
+      id: map["id"],
+      name: map["name"],
+      created_at: Util.parse_iso8601(map["created_at"]),
+      deleted: map["deleted"]
+    }
+  end
+end