add typesecs and docstrings

Follow Elixir naming conventions by using question mark suffix for boolean
functions. Renamed mail_allowlisted to signup_allowed? and mail_allowlisted_fun
to signup_allowed_fun throughout the codebase.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

lib/basic_signup_allowlist.ex

@@ -1,10 +1,18 @@
 defmodule BasicSignupAllowlist do
   import FunCore.BasicSignupAllowlist
 
+  @signup_allowlist_emails "SIGNUP_ALLOWLIST_EMAILS"
+
   @moduledoc """
   Checks if an email address is allowed based on the SIGNUP_ALLOWLIST_EMAILS env variable.
   """
 
+  @doc """
+  Returns the name of the environment variable used for the signup allowlist.
+  """
+  @spec signup_allowlist_emails() :: String.t()
+  def signup_allowlist_emails, do: @signup_allowlist_emails
+
   @doc """
   Checks if an email address is allowed based on the SIGNUP_ALLOWLIST_EMAILS env variable.
 
@@ -19,15 +27,16 @@ defmodule BasicSignupAllowlist do
   ## Examples
 
       iex> System.delete_env("SIGNUP_ALLOWLIST_EMAILS")
-      iex> BasicSignupAllowlist.mail_allowlisted("joe@example.com")
+      iex> BasicSignupAllowlist.signup_allowed?("joe@example.com")
       false
-      iex> System.put_env("SIGNUP_ALLOWLIST_EMAILS","*")
-      iex> BasicSignupAllowlist.mail_allowlisted("joe@example.com")
+      iex> System.put_env("SIGNUP_ALLOWLIST_EMAILS", "*")
+      iex> BasicSignupAllowlist.signup_allowed?("joe@example.com")
       true
 
   """
-  def mail_allowlisted(email) do
-    env_value = System.get_env("SIGNUP_ALLOWLIST_EMAILS")
-    mail_allowlisted_fun(env_value, email)
+  @spec signup_allowed?(String.t()) :: boolean()
+  def signup_allowed?(email) do
+    env_value = System.get_env(@signup_allowlist_emails)
+    signup_allowed_fun(env_value, email)
   end
 end

lib/fun_core/basic_signup_allowlist.ex

@@ -1,15 +1,31 @@
 defmodule FunCore.BasicSignupAllowlist do
+  @moduledoc """
+  Functional core for email allowlist checking logic.
+  """
+
+  @doc """
+  Normalizes an email address by trimming whitespace and converting to lowercase.
+  """
+  @spec normalize(String.t()) :: String.t()
   def normalize(email) do
     email |> String.trim() |> String.downcase()
   end
 
+  @doc """
+  Converts a comma-separated string of email addresses into a normalized list.
+  """
+  @spec addresses_as_list(String.t()) :: [String.t()]
   def addresses_as_list(addresses_str) do
     addresses_str
     |> String.split(",")
     |> Enum.map(&normalize/1)
   end
 
-  def mail_allowlisted_fun(signups_allowed, email_received) do
+  @doc """
+  Checks if an email is allowed based on the allowlist configuration.
+  """
+  @spec signup_allowed_fun(String.t() | nil, String.t()) :: boolean()
+  def signup_allowed_fun(signups_allowed, email_received) do
     case signups_allowed do
       nil -> false
       "*" -> true

test/basic_signup_allowlist_test.exs

@@ -3,27 +3,27 @@ defmodule BasicSignupAllowlistTest do
   doctest BasicSignupAllowlist
 
   defp allow_signups_for(allowlist) do
-    System.put_env("SIGNUP_ALLOWLIST_EMAILS", allowlist)
+    System.put_env(BasicSignupAllowlist.signup_allowlist_emails(), allowlist)
   end
 
   describe "setup in describe block" do
     setup do
       on_exit(fn ->
         # resetting values did not work, so 'just' set it to the effect without this module configured.
-        System.put_env("SIGNUP_ALLOWLIST_EMAILS", "*")
+        System.put_env(BasicSignupAllowlist.signup_allowlist_emails(), "*")
       end)
 
       :ok
     end
 
     test "When not set, not allowlisted" do
-      System.delete_env("SIGNUP_ALLOWLIST_EMAILS")
-      refute BasicSignupAllowlist.mail_allowlisted("joe@example.com")
+      System.delete_env(BasicSignupAllowlist.signup_allowlist_emails())
+      refute BasicSignupAllowlist.signup_allowed?("joe@example.com")
     end
 
     test "When set to star, allowlisted" do
       allow_signups_for("*")
-      assert BasicSignupAllowlist.mail_allowlisted("joe@example.com")
+      assert BasicSignupAllowlist.signup_allowed?("joe@example.com")
     end
   end
 end

test/fun_core/basic_signup_allowlist_test.exs

@@ -16,25 +16,25 @@ defmodule FunCore.BasicSignupAllowlistTest do
 
   describe "Not allowlisted when allowed list is" do
     test "not set" do
-      refute(mail_allowlisted_fun(nil, "joe@example.com"))
+      refute(signup_allowed_fun(nil, "joe@example.com"))
     end
 
     test "empty" do
-      refute(mail_allowlisted_fun("j", "joe@example.com"))
+      refute(signup_allowed_fun("j", "joe@example.com"))
     end
   end
 
   describe "Allowlisted when" do
     test "*" do
-      assert(mail_allowlisted_fun("*", "jane@example.com"))
+      assert(signup_allowed_fun("*", "jane@example.com"))
     end
 
     test "Multiple set and one match" do
-      assert(mail_allowlisted_fun("joe@example.com, jane@example.com", "jane@example.com"))
+      assert(signup_allowed_fun("joe@example.com, jane@example.com", "jane@example.com"))
     end
 
     test "Matches with different casings" do
-      assert(mail_allowlisted_fun("joe@Example.com, jane@example.com", "Joe@example.com"))
+      assert(signup_allowed_fun("joe@Example.com, jane@example.com", "Joe@example.com"))
     end
   end
 end