svix

defmodule Svix do
  @moduledoc """
  Elixir client for the Svix webhook API.

  ## Quick Start

      client = Svix.new("sk_your_token.eu")

      {:ok, app} = Svix.Application.create(client, %{name: "My App"})
      {:ok, _msg} = Svix.Message.create(client, app["id"], %{
        event_type: "invoice.paid",
        payload: %{id: "inv_123", amount: 1000}
      })

  ## Regional URLs

  The token suffix automatically selects the regional API endpoint.
  Override with the `:server_url` option:

      client = Svix.new("sk_token", server_url: "https://self-hosted.example.com")

  ## Error Handling

  All functions return `{:ok, result}` or `{:error, exception}` tuples.
  Bang variants (e.g., `create!`) raise on error.

      case Svix.Application.get(client, "app_123") do
        {:ok, app} -> app
        {:error, %Svix.Error.ApiError{status: 404}} -> nil
      end

  """

  @doc """
  Create a new Svix API client.

  Delegates to `Svix.Client.new/2`. See that module for full option
  documentation and regional URL resolution.

  ## Options

    * `:server_url` - Override the base URL (default: auto-detected from token)
    * `:timeout` - Request timeout in ms (default: `15_000`)
    * `:req_options` - Additional options passed to `Req.new/1`

  ## Examples

      client = Svix.new("sk_test_token.eu")

      client = Svix.new("sk_test_token", server_url: "https://self-hosted.example.com")

  """
  @spec new(String.t(), keyword()) :: Svix.Client.t()
  defdelegate new(token, opts \\ []), to: Svix.Client

  @doc """
  Check API server health.

  ## Examples

      {:ok, %{"status" => "ok"}} = Svix.health(client)

  """
  @spec health(Svix.Client.t()) :: {:ok, map()} | {:error, Exception.t()}
  def health(client) do
    Svix.Http.request(client, :get, "/api/v1/health")
  end

  @doc "Bang version of `health/1`. Raises on error."
  @spec health!(Svix.Client.t()) :: map()
  def health!(client) do
    client |> health() |> Svix.Http.unwrap!()
  end
end