@spec authorize_url(MyAnimeList.Client.t(), String.t(), String.t()) :: String.t()

MAL authorization URL to redirect the user to.

@spec configured?(String.t() | nil) :: boolean()

Whether a usable client id / access token was provided.

@spec ensure_fresh(MyAnimeList.Client.t(), MyAnimeList.Token.t(), keyword()) ::
  {:ok, MyAnimeList.Token.t()} | {:error, term()}

Return a non-expired token, refreshing via refresh_token/3 if the current one is within a minute of expiry (or has no expires_at). The returned token may be the same struct — persist it if it changed.

@spec exchange_code(MyAnimeList.Client.t(), String.t(), String.t(), keyword()) ::
  {:ok, MyAnimeList.Token.t()} | {:error, term()}

Exchange an authorization code for a MyAnimeList.Token.

@spec get(media(), term(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}

Full metadata for a title id, normalized for enrichment. Common fields: id, url, title, cover_url, synopsis, genres, score, rank, popularity, num_users, media_type, status, year, year_start, year_end. Manga adds num_chapters, num_volumes, authors; anime adds num_episodes, studios (the other media's fields are present as nil/[]).

Options: :req_options.

@spec list_scores(media(), String.t(), keyword()) ::
  {:ok, %{optional(integer()) => integer()}}

The authenticated user's list as %{mal_id => score} (score 0 = on the list but unrated; absent = not on the list).

@spec list_statuses(media(), String.t(), keyword()) ::
  {:ok, %{optional(integer()) => map()}}

The authenticated user's whole list as %{mal_id => list_status_map} (the raw list_status object with "status", "score", the progress field, …). Paginates. Best-effort — returns {:ok, map} even on a partial/failed fetch.

@spec my_progress(media(), String.t(), term(), keyword()) ::
  {:ok, integer()} | {:error, term()}

The authenticated user's current progress for a title (episodes watched / chapters read), or 0 if it's not on their list. Useful to seed a push high-water mark so linking never regresses existing MAL progress.

@spec new_code_verifier() :: String.t()

A fresh PKCE code verifier (also used verbatim as the challenge).

@spec oauth_ready?(MyAnimeList.Client.t()) :: boolean()

True when the client has both an id and a secret configured.

@spec page_url(media(), term()) :: String.t()

Public MAL page URL for a title.

@spec progress_key(media()) :: String.t()

The my_list_status field that carries a user's progress for media ("num_episodes_watched" for anime, "num_chapters_read" for manga) — handy when building an update_list_status/5 fields map.

@spec refresh_token(MyAnimeList.Client.t(), String.t(), keyword()) ::
  {:ok, MyAnimeList.Token.t()} | {:error, term()}

Exchange a refresh token for a fresh MyAnimeList.Token.

@spec search(media(), String.t(), String.t(), keyword()) ::
  {:ok, [map()]} | {:error, term()}

Search media by title. Returns {:ok, [%{id, title, cover_url, score, media_type, year}]}.

Options: :limit (default 10), :req_options.

@spec status_label(String.t() | nil) :: String.t() | nil

MAL publication/airing status → display label (anime + manga).

@spec statuses(media()) :: [String.t()]

The valid list-status values MAL accepts for media.

@spec update_list_status(media(), String.t(), term(), map(), keyword()) ::
  {:ok, map()} | {:error, term()}

Update the authenticated user's list entry (PATCH /{media}/{id}/my_list_status). fields is a plain map, e.g. %{num_episodes_watched: 12, status: "watching"} for anime or %{num_chapters_read: 12, status: "reading"} for manga.

@spec username(
  String.t(),
  keyword()
) :: String.t() | nil

The authenticated user's MAL username, or nil.

@spec year_range(integer() | nil, integer() | nil) :: String.t() | nil

Year range for display: "1997", "1997–2003", or "1997–" (ongoing).