feat: Improve config

Author: rafaeelaudibert

lib/posthog/application.ex

@@ -8,6 +8,9 @@ defmodule Posthog.Application do
   def cache_name, do: @cache_name
 
   def start(_type, args) do
+    # Validate configuration before starting
+    Posthog.Config.validate_config!()
+
     cache_name = Keyword.get(args, :cache_name, @cache_name)
 
     children = [

lib/posthog/client.ex

@@ -67,8 +67,6 @@ defmodule Posthog.Client do
       Posthog.Client.feature_flags("user_123", groups: %{team: "engineering"})
   """
 
-  @app :posthog
-
   @typedoc """
   HTTP headers in the format expected by :hackney.
   """
@@ -171,7 +169,7 @@ defmodule Posthog.Client do
   @spec capture(event(), distinct_id(), properties(), opts()) ::
           {:ok, response()} | {:error, response() | term()}
   def capture(event, distinct_id, properties \\ %{}, opts \\ []) when is_list(opts) do
-    if enabled_capture?() do
+    if Posthog.Config.enabled_capture?() do
       timestamp =
         Keyword.get_lazy(opts, :timestamp, fn ->
           DateTime.utc_now() |> DateTime.to_iso8601()
@@ -214,7 +212,7 @@ defmodule Posthog.Client do
   end
 
   def batch(events, opts, headers) do
-    if enabled_capture?() do
+    if Posthog.Config.enabled_capture?() do
       timestamp = Keyword.get_lazy(opts, :timestamp, fn -> DateTime.utc_now() end)
 
       body =
@@ -362,10 +360,10 @@ defmodule Posthog.Client do
   defp post!(path, %{} = body, headers) do
     body =
       body
-      |> Map.put(:api_key, api_key())
-      |> encode(json_library())
+      |> Map.put(:api_key, Posthog.Config.api_key())
+      |> encode(Posthog.Config.json_library())
 
-    url = api_url() <> path
+    url = Posthog.Config.api_url() <> path
 
     :hackney.post(url, headers, body, [])
     |> handle()
@@ -391,56 +389,14 @@ defmodule Posthog.Client do
     response = %{status: status, headers: headers, body: nil}
 
     with {:ok, body} <- :hackney.body(ref),
-         {:ok, json} <- json_library().decode(body) do
+         {:ok, json} <- Posthog.Config.json_library().decode(body) do
       %{response | body: json}
     else
       _ -> response
     end
   end
 
   @doc false
-  @spec api_url() :: binary()
-  defp api_url do
-    case Application.get_env(@app, :api_url) do
-      url when is_bitstring(url) ->
-        url
-
-      term ->
-        raise """
-        Expected a string API URL, got: #{inspect(term)}. Set a
-        URL and key in your config:
-
-            config :posthog,
-              api_url: "https://posthog.example.com",
-              api_key: "my-key"
-        """
-    end
-  end
-
-  @doc false
-  @spec api_key() :: binary()
-  defp api_key do
-    case Application.get_env(@app, :api_key) do
-      key when is_bitstring(key) ->
-        key
-
-      term ->
-        raise """
-        Expected a string API key, got: #{inspect(term)}. Set a
-        URL and key in your config:
-
-            config :posthog,
-              api_url: "https://posthog.example.com",
-              api_key: "my-key"
-        """
-    end
-  end
-
-  @doc false
-  defp enabled_capture? do
-    Application.get_env(@app, :enabled_capture, true)
-  end
-
   defp disabled_capture_response do
     {:ok, %{status: 200, headers: [], body: nil}}
   end
@@ -450,12 +406,6 @@ defmodule Posthog.Client do
   defp encode(data, Jason), do: Jason.encode_to_iodata!(data)
   defp encode(data, library), do: library.encode!(data)
 
-  @doc false
-  @spec json_library() :: module()
-  defp json_library do
-    Application.get_env(@app, :json_library, Jason)
-  end
-
   @doc false
   @spec lib_properties() :: map()
   defp lib_properties do

lib/posthog/config.ex

@@ -0,0 +1,114 @@
+defmodule Posthog.Config do
+  @moduledoc """
+  Handles configuration validation and defaults for the PostHog client.
+
+  This module validates the configuration at compile time and provides
+  sensible defaults for optional values.
+  """
+
+  @app :posthog
+
+  @doc """
+  Validates and returns the API URL from the configuration.
+
+  Raises a helpful error message if the URL is missing or invalid.
+  """
+  def api_url do
+    case Application.get_env(@app, :api_url) do
+      url when is_binary(url) and url != "" ->
+        url
+
+      nil ->
+        raise """
+        PostHog API URL is not configured. Please add it to your config:
+
+            config :posthog,
+              api_url: "https://app.posthog.com"  # or your self-hosted instance
+        """
+
+      url ->
+        raise """
+        Invalid PostHog API URL: #{inspect(url)}
+
+        Expected a non-empty string URL, for example:
+            config :posthog,
+              api_url: "https://app.posthog.com"  # or your self-hosted instance
+        """
+    end
+  end
+
+  @doc """
+  Validates and returns the API key from the configuration.
+
+  Raises a helpful error message if the key is missing or invalid.
+  """
+  def api_key do
+    case Application.get_env(@app, :api_key) do
+      key when is_binary(key) and key != "" ->
+        key
+
+      nil ->
+        raise """
+        PostHog API key is not configured. Please add it to your config:
+
+            config :posthog,
+              api_key: "phc_your_project_api_key"
+        """
+
+      key ->
+        raise """
+        Invalid PostHog API key: #{inspect(key)}
+
+        Expected a non-empty string API key, for example:
+            config :posthog,
+              api_key: "phc_your_project_api_key"
+        """
+    end
+  end
+
+  @doc """
+  Returns whether event capture is enabled.
+
+  Defaults to true if not configured.
+  """
+  def enabled_capture? do
+    Application.get_env(@app, :enabled_capture, true)
+  end
+
+  @doc """
+  Returns the JSON library to use for encoding/decoding.
+
+  Defaults to Jason if not configured.
+  """
+  def json_library do
+    Application.get_env(@app, :json_library, Jason)
+  end
+
+  @doc """
+  Validates the entire PostHog configuration at compile time.
+
+  This ensures that all required configuration is present and valid
+  before the application starts.
+  """
+  def validate_config! do
+    # Validate required config
+    api_url()
+    api_key()
+
+    # Validate optional config
+    if json_library() != Jason do
+      unless Code.ensure_loaded?(json_library()) do
+        raise """
+        Configured JSON library #{inspect(json_library())} is not available.
+
+        Make sure to add it to your dependencies in mix.exs:
+            defp deps do
+              [{#{inspect(json_library())}, "~> x.x"}]
+            end
+        """
+      end
+    end
+
+    :ok
+  end
+end