defmodule Mv.EmailSync.Loader do
  @moduledoc """
  Helper functions for loading linked records in email synchronization.
  Centralizes the logic for retrieving related User/Member entities.

  ## Authorization

  This module runs systemically and accepts optional actor parameters.
  When called from hooks/changes, actor is extracted from changeset context.
  When called directly, actor should be provided for proper authorization.

  All functions accept an optional `actor` parameter that is passed to Ash operations
  to ensure proper authorization checks are performed.
  """
  alias Mv.Helpers

  @doc """
  Loads the member linked to a user, returns nil if not linked or on error.

  Accepts optional actor for authorization.
  """
  def get_linked_member(user, actor \\ nil)
  def get_linked_member(%{member_id: nil}, _actor), do: nil

  def get_linked_member(%{member_id: id}, actor) do
    opts = Helpers.ash_actor_opts(actor)

    case Ash.get(Mv.Membership.Member, id, opts) do
      {:ok, member} -> member
      {:error, _} -> nil
    end
  end

  @doc """
  Loads the user linked to a member, returns nil if not linked or on error.

  Accepts optional actor for authorization.
  """
  def get_linked_user(member, actor \\ nil) do
    opts = Helpers.ash_actor_opts(actor)

    case Ash.load(member, :user, opts) do
      {:ok, %{user: user}} -> user
      {:error, _} -> nil
    end
  end

  @doc """
  Loads the user linked to a member, returning an error tuple if not linked.
  Useful when a link is required for the operation.

  Accepts optional actor for authorization.
  """
  def load_linked_user!(member, actor \\ nil) do
    opts = Helpers.ash_actor_opts(actor)

    case Ash.load(member, :user, opts) do
      {:ok, %{user: user}} when not is_nil(user) -> {:ok, user}
      {:ok, _} -> {:error, :no_linked_user}
      {:error, _} = error -> error
    end
  end
end