@spec add_auth_headers(
  map() | keyword(),
  keyword()
) :: {:ok, map() | keyword()} | {:error, any()}

Adds authorization headers to a request if a token is available.

Options:

• :token_manager - PID or name of TokenManager process
• :token - Static token to use (alternative to token_manager)
• :auth_type - Authorization type (default: "Bearer")

@spec handle_response({:ok, any()} | {:error, any()}, map()) ::
  {:ok, any()} | {:retry, map()} | {:error, any()}

Processes a response and handles authorization errors.

Returns:

• {:ok, response} - Response is fine, continue processing
• {:retry, auth_params} - Need to retry with authentication
• {:error, reason} - Unrecoverable error

@spec wrap_request_fn(
  (map() -> {:ok, any()} | {:error, any()}),
  keyword()
) :: (map() -> {:ok, any()} | {:error, any()})

Creates an authorization-aware request function.

This wraps a request function to automatically add auth headers and handle authorization errors with retry logic.