evercycle_api.py
================

.. module:: evercycle_api

Command-line client and Python library for the Evercycle API.

Classes
-------

.. py:class:: Colors

   ANSI color constants for terminal output.

   .. py:attribute:: GREEN
   .. py:attribute:: YELLOW
   .. py:attribute:: RED
   .. py:attribute:: NC

.. py:class:: EvercycleApiClient(api_dir=None)

   Main client class for authenticating and calling Evercycle APIs.

   :param str api_dir: Base directory containing ``auth.properties`` and
                       ``config/`` sub-directory. Defaults to ``os.getcwd()``.

   .. py:method:: load_auth_properties() -> dict[str, str]

      Load ``auth.properties`` key/value pairs into a dictionary.

   .. py:method:: save_auth_properties(props) -> None

      Write a dictionary of properties back to ``auth.properties``.

   .. py:method:: authenticate(username=None, password=None) -> bool

      Authenticate with ``/v1/auth/signin``.

      If credentials are not provided, they are loaded from
      ``config/auth-signin.json``.

      On success, extracts ``AccessToken``, ``IdToken``, and ``RefreshToken``
      and saves them to ``auth.properties``.

      :return: True on success, False on failure.

   .. py:method:: get_available_apis() -> dict[str, dict]

      Scan the ``config/`` directory for ``*.json`` files and build a map of
      available APIs. Each entry contains ``method``, ``path``, ``description``,
      and ``config_file``.

   .. py:method:: list_apis() -> None

      Print a formatted list of available APIs to the terminal.

   .. py:method:: call_api(api_name: str, *args) -> bool

      Call a specific API endpoint using its JSON config.

      **Argument mapping by API name:**

      * ``get-asset-id``: first arg replaces ``{id}`` in path
      * ``edit-asset-id``: first arg = id, second arg = JSON body string
      * ``grade``: first arg = id, second arg = grade, third arg = JSON body
      * ``create``, ``single-confirm``, ``create-request``: first arg = JSON body

      Injects ``access-token`` and ``Authorization`` headers from
      ``auth_props`` before making the request.

      Prints request details and response to stdout and returns True/False.

      :param str api_name: Name of the API config.
      :param args: Variable positional arguments (see mapping above).
      :return: True if the HTTP call succeeds (2xx), False otherwise.

Functions
---------

.. py:function:: main()

   CLI entry point supporting three subcommands:

   * ``auth [--username] [--password]``
   * ``call <api_name> [params...]``
   * ``list``