api_client.py
=============

.. module:: api_client

A flexible, generic HTTP API client built on ``requests.Session``.

Classes
-------

.. py:class:: ApiClient(base_url=None, auth_token=None, config_file="api_config.ini", skip_auth_prompt=False)

   Generic API client that can target any REST API.

   :param str base_url: API base URL (e.g., ``https://api.evercycle.io``).
   :param str auth_token: Bearer token for Authorization header.
   :param str config_file: INI file for persisting settings.
   :param bool skip_auth_prompt: If True, do not prompt for a token.

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

      Persist current ``base_url`` and ``auth_token`` to the INI file.

   .. py:method:: discover_endpoints() -> dict | None

      Attempt to discover API endpoints by probing common paths:
      ``methods``, ``endpoints``, ``swagger``, ``swagger.json``,
      ``openapi``, ``openapi.json``, ``api-docs``.

      Caches successful results in the INI file under ``endpoints_cache``.

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

      Print discovered endpoints. Supports Swagger/OpenAPI ``paths`` format
      and custom ``methods`` format.

   .. py:method:: _print_nested_endpoints(data, prefix="") -> None

      Recursively print nested endpoint dictionaries or lists.

   .. py:method:: call_endpoint(endpoint, method="GET", params=None, data=None, headers=None)

      Execute an HTTP request.

      :param str endpoint: URL path (joined with ``base_url``).
      :param str method: HTTP method.
      :param dict params: Query parameters.
      :param dict data: Request body (dict is auto-converted to JSON).
      :param dict headers: Additional request headers.
      :return: Parsed JSON response, raw text, or None on error.

      **Side effects:** Appends call metadata to ``self.history``.

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

      Launch a text-based interactive menu (choices 1-6):

      1. List endpoints
      2. Call an endpoint (prompts for path, method, params, body)
      3. View call history
      4. Change base URL
      5. Change authentication token
      6. Exit

Functions
---------

.. py:function:: main()

   CLI entry point supporting:

   * ``--url``, ``--token``, ``--config``, ``--endpoint``, ``--method``,
     ``--params``, ``--data``, ``--list``
   * Falls back to ``interactive_mode()`` if no explicit operation given.