campaign_flow

defmodule CampaignFlow.Client do
  @moduledoc """
  Main client module for the Campaign Flow API.

  This module provides a convenient interface for interacting with the Campaign Flow API
  using OAuth2 authentication and the Req HTTP client library.

  ## Configuration

  You can configure the client in your config files:

      config :campaign_flow,
        base_url: "https://app.campaignflow.com.au/api/v2",
        client_id: "your_client_id",
        client_secret: "your_client_secret"

  Or pass configuration directly when creating a client:

      client = CampaignFlow.Client.new(
        base_url: "https://app.campaignflow.com.au/api/v2",
        client_id: "your_client_id",
        client_secret: "your_client_secret"
      )

  ## Usage

      # Create a new client
      client = CampaignFlow.Client.new(
        client_id: "your_client_id",
        client_secret: "your_client_secret"
      )

      # Make API calls using resource modules
      {:ok, campaigns} = CampaignFlow.Client.Campaigns.list(client)
      {:ok, campaign} = CampaignFlow.Client.Campaigns.get(client, campaign_id)
  """

  @type t :: %__MODULE__{
          environment: atom(),
          base_url: String.t(),
          token_manager: atom(),
          req_options: keyword()
        }

  defstruct [
    :environment,
    :base_url,
    :token_manager,
    req_options: []
  ]

  # Public API

  @doc """
  Creates a new Campaign Flow API client.

  The client credentials are configured via Application config, not passed directly.
  Tokens are managed by a TokenManager process for the specified environment.

  ## Options

    * `:environment` - The environment to use (`:prod`, `:test`, or custom atom) (required)
    * `:base_url` - The base URL for the API (optional, overrides environment default)
    * `:req_options` - Additional options to pass to Req

  ## Examples

      client = CampaignFlow.Client.new(environment: :prod)
      #=> %CampaignFlow.Client{environment: :prod, ...}

      client = CampaignFlow.Client.new(environment: :test)
      #=> %CampaignFlow.Client{environment: :test, base_url: "https://test.campaignflow.com.au/api/v2", ...}

      client = CampaignFlow.Client.new(environment: :prod, base_url: "https://custom.example.com/api/v2")
      #=> %CampaignFlow.Client{environment: :prod, base_url: "https://custom.example.com/api/v2", ...}
  """
  @spec new(keyword()) :: t()
  def new(opts \\ []) do
    environment = opts[:environment] || raise("environment is required (e.g., :prod or :test)")
    token_manager = CampaignFlow.Application.token_manager_name(environment)

    # Get base_url from options, or look it up from config
    base_url =
      opts[:base_url] ||
        get_environment_base_url(environment) ||
        raise("base_url not configured for environment: #{environment}")

    %__MODULE__{
      environment: environment,
      base_url: base_url,
      token_manager: token_manager,
      req_options: opts[:req_options] || []
    }
  end

  defp get_environment_base_url(environment) do
    config = Application.get_env(:campaign_flow, :environments, [])
    env_config = Keyword.get(config, environment)
    env_config && Keyword.get(env_config, :base_url)
  end

  @doc """
  Creates a new client for the test environment.

  Convenience function that sets environment to :test.

  ## Examples

      client = CampaignFlow.Client.test()
      #=> %CampaignFlow.Client{environment: :test, base_url: "https://test.campaignflow.com.au/api/v2", ...}
  """
  @spec test(keyword()) :: t()
  def test(opts \\ []) do
    opts
    |> Keyword.put(:environment, :test)
    |> new()
  end
end