YARD Documentation

YARD is not optional polish. After any feature or fix that adds or changes
public Ruby API (classes, modules, public methods):

1. Add or update YARD on those surfaces before the work is considered done.
2. Do not skip YARD because "the PR is small" or "I'll do it later."

Task lists from generate-tasks MUST include explicit YARD sub-tasks after
implementation. If you only wrote specs + code, stop and document before PR.

All generated YARD content MUST be in English: class descriptions, method summaries,
@param/@return descriptions, @example blocks, and any other inline documentation.
Do not generate documentation in another language unless the user explicitly requests it.

# Responsible for validating and executing animal transfers between shelters.
# @since 1.2.0
module AnimalTransfers
  class TransferService

# Performs the transfer and returns a standardized response.
# @param params [Hash] Transfer parameters
# @option params [Hash] :source_shelter Shelter hash with :shelter_id
# @option params [Hash] :target_shelter Target shelter with :shelter_id
# @return [Hash] Result with :success and :response keys
def self.call(params)

# Fetches the token; caches it for subsequent calls.
# @raise [Client::Error] when credentials are missing or request fails
# @return [String] Bearer token
def token

# @example Basic usage
#   result = TransferService.call(source_shelter: { shelter_id: 1 }, target_shelter: { shelter_id: 2 })
#   result[:success] # => true

# Validates source and target shelters and returns the first validation error.
# @param source_id [Integer] Source shelter ID
# @param target_id [Integer] Target shelter ID
# @return [nil, String] nil if valid, error message otherwise
def self.validate_shelters!(source_id, target_id)

# Validates stuff.  (Too vague; no @param/@return)
def self.validate_shelters!(source_id, target_id)

# Valida los refugios origen y destino.  (Must be in English)
def self.validate_shelters!(source_id, target_id)