@callback add_token(String.t(), String.t(), String.t(), map()) ::
  {:ok, term()} | {:error, term()}

@callback check_model_access(term(), String.t()) :: :ok | {:error, String.t()}

@callback check_quota(term()) :: :ok | {:error, String.t()}

@callback check_service_quota(term(), String.t()) :: :ok | {:error, String.t()}

@callback create_key(String.t(), map()) :: {:ok, term(), String.t()} | {:error, term()}

@callback delete_key(term()) :: {:ok, term()} | {:error, term()}

@callback find_key(String.t()) :: term() | nil

@callback find_trace_by_request_id(String.t()) :: term() | nil

@callback get_cache_ratio_in_window(String.t(), integer()) :: {float(), integer()}

@callback get_daily_stats(map()) :: [term()]

@callback get_message_count_in_window(String.t(), integer()) :: integer()

@callback get_messages(map()) :: [term()]

@callback get_service_usage_in_window(String.t(), String.t(), integer()) :: integer()

@callback get_stats(map()) :: map()

@callback get_tokens(String.t(), String.t()) :: [term()]

@callback get_trace(term()) :: term() | nil

@callback get_trace_feedback(integer()) :: [term()]

@callback get_traces(map()) :: [term()]

@callback get_usage_in_window(String.t(), integer()) :: map()

@callback list_keys(map()) :: [term()]

@callback list_tokens(map()) :: [term()]

@callback list_trace_feedback(term()) :: [term()]

@callback log_message(map()) :: {:ok, term()} | {:error, term()}

@callback record_service_usage(map()) :: {:ok, term()} | {:error, term()}

@callback record_trace(map()) :: {:ok, term()} | {:error, term()}

@callback record_trace_feedback(map()) :: {:ok, term()} | {:error, term()}

@callback record_usage(map()) :: {:ok, term()} | {:error, term()}

@callback remove_token(term()) :: {:ok, term()} | {:error, term()}

@callback seed_tokens_from_env([map()]) :: :ok

@callback set_token_enabled(term(), boolean()) :: {:ok, term()} | {:error, term()}

@callback update_key_models(term(), list() | nil) :: {:ok, term()} | {:error, term()}

@callback update_key_quota(term(), map()) :: {:ok, term()} | {:error, term()}

@callback update_key_usage(term(), map()) :: term()

@callback update_message_usage(term(), map()) :: {:ok, term()} | {:error, term()}

@callback update_token_oauth(term(), map()) :: {:ok, term()} | {:error, term()}

@callback update_token_proxy(term(), String.t() | nil) :: {:ok, term()} | {:error, term()}