Operational Flows
=================

This section details the step-by-step operational flows for the most common
transactions within the Evercycle API system.

Flow 1: Authenticate and Store Tokens
-------------------------------------

**Actors:** HTTP client, Flask server, Evercycle backend

1. Client sends ``POST /api/auth`` with JSON body containing ``username`` and ``password``.
2. ``api_server.py`` validates that both fields are present; returns 400 if not.
3. ``api_server.py`` calls ``api_client.authenticate(username, password)``.
4. ``evercycle_api.py`` builds the payload and POSTs to ``https://api.evercycle.io/v1/auth/signin``.
5. On success, the backend returns an ``AuthenticationResult`` with:
   * ``AccessToken``
   * ``IdToken``
   * ``RefreshToken``
6. ``evercycle_api.py`` writes these three tokens to ``evercycle-api/auth.properties``.
7. ``api_server.py`` updates global variables:
   * ``refresh_token`` ← RefreshToken
   * ``token_expiry`` ← now + 3600 seconds
8. Flask session is marked authenticated.
9. Response ``200 OK`` with status "success" is returned to the client.

Flow 2: Call a Protected API with Valid Token
---------------------------------------------

**Actors:** HTTP client, Flask server, Evercycle backend

1. Client sends a request to ``/api/get-all`` with method GET.
2. ``call_api('get-all')`` is invoked.
3. ``refresh_auth_token()`` is called.
4. ``is_token_valid()`` checks ``token_expiry`` against ``now + 60s``.
5. Token is valid → function returns ``True`` immediately.
6. ``api_server.py`` prepares parameters:
   * For GET, parameters come from ``request.args`` (query string).
   * No special path-parameter handling needed for ``get-all``.
7. ``api_client.call_api('get-all')`` is executed.
8. Config file ``config/get-all.json`` is loaded.
9. Auth headers are injected:
   * ``access-token`` ← ``access_token`` from ``auth.properties``
   * ``Authorization`` ← ``id_token`` from ``auth.properties``
10. HTTP GET is dispatched to ``https://api.evercycle.io/v1/asset``.
11. Response JSON is returned to the client wrapped in:
    ``{"status": "success", "data": <response>}``

Flow 3: Call an API with Expired Token (Auto-Refresh)
-----------------------------------------------------

**Actors:** HTTP client, Flask server, Evercycle backend

1. Client sends ``GET /api/get-all``.
2. ``call_api('get-all')`` begins.
3. ``refresh_auth_token()`` detects that ``token_expiry`` has passed.
4. Server attempts to POST to ``https://api.evercycle.io/v1/auth/refresh``
   with the stored ``refresh_token``.
5. If refresh succeeds:
   * New tokens are extracted.
   * ``auth.properties`` is overwritten.
   * ``token_expiry`` is updated.
   * Flow continues as in Flow 2.
6. If refresh fails:
   * Server falls back to re-authentication.
   * It reads ``config/auth-signin.json`` for username/password.
   * Calls ``api_client.authenticate(username, password)``.
   * On success, updates globals and proceeds.
   * On failure, returns ``401 Unauthorized`` to the client.

Flow 4: Get Asset by ID (Runtime Path Patching)
-----------------------------------------------

**Actors:** HTTP client, Flask server

1. Client sends ``GET /api/get-asset-id?id=12345``.
2. ``call_api('get-asset-id')`` is invoked.
3. Authentication check passes (Flow 2/3 logic).
4. Because ``api_name == 'get-asset-id'``, the server enters special handling:
   * Extracts ``asset_id`` from ``request.args.get('id')``.
   * Overrides ``api_info['path']`` to ``/v1/asset/{asset_id}``.
   * Dynamically monkey-patches ``api_client.call_api`` with ``patched_call_api``.
5. The patched function ignores the normal config-driven URL construction and
   directly builds ``https://api.evercycle.io/v1/asset/12345``.
6. It injects headers and calls ``requests.get``.
7. The response is parsed and returned to the client.
8. Note: the monkey-patch is temporary for the duration of that single call.

Flow 5: Create a New Asset
--------------------------

**Actors:** HTTP client, Flask server

1. Client sends ``POST /api/create`` with JSON body fields.
2. ``call_api('create')`` begins.
3. Authentication is verified.
4. Server loads ``config/create.json`` to obtain default body values.
5. Request JSON body is merged on top of the defaults:
   ``merged_data = default_body.copy(); merged_data.update(request.json)``
6. The merged JSON string is passed as a parameter to ``api_client.call_api``.
7. ``api_client.call_api`` parses the JSON and sets ``user_config['body']``.
8. HTTP POST is dispatched to ``https://api.evercycle.io/v1/asset/create``.
9. Response is returned to the client.

Flow 6: Edit Asset (PUT with Path Parameter)
--------------------------------------------

**Actors:** HTTP client, Flask server

1. Client sends ``PUT /api/edit-asset-id`` with JSON body containing ``id``
   and any fields to update.
2. ``call_api('edit-asset-id')`` begins.
3. Authentication is verified.
4. Server extracts ``asset_id`` from body ``id`` field.
5. It loads ``config/edit-asset-id.json`` for default body values.
6. Request body (minus ``id``) is merged into defaults.
7. ``api_info['path']`` and ``api_info['url']`` are both overridden to
   ``/v1/asset/{asset_id}``.
8. ``api_client.call_api`` receives ``asset_id`` and the merged JSON string.
9. The path parameter ``{id}`` is substituted in the URL.
10. HTTP PUT is dispatched.

Flow 7: Grade Update (PUT with Multiple Path Parameters)
--------------------------------------------------------

**Actors:** HTTP client, Flask server

1. Client sends ``PUT /api/grade`` with JSON body containing ``id``, ``grade``,
   and optionally ``price``.
2. ``call_api('grade')`` begins.
3. Server extracts ``asset_id`` and ``grade_name`` from the body.
4. It loads ``config/grade.json`` for defaults.
5. Body fields other than ``id`` and ``grade`` are merged into defaults.
6. ``api_info['path']`` and ``api_info['url']`` are overridden to
   ``/v1/pricebook/{asset_id}/{grade_name}``.
7. ``api_client.call_api`` substitutes both path parameters.
8. HTTP PUT is dispatched to the constructed URL.

Flow 8: CLI Auth and Config Generation
--------------------------------------

**Actors:** Terminal user, ``api_runner.py``, filesystem

1. User runs ``python3 api_runner.py generate`` inside ``evercycle-api/``.
2. ``ApiRunner.load_endpoints()`` reads all ``*.md`` files in the directory.
3. Each markdown file is parsed by ``parse_markdown_file()``:
   * First line → ``path``
   * Second line → ``description``
   * Regex search → ``method`` and ``url``
   * Table sections → ``headers``, ``parameters``, ``body_params``
4. For each endpoint, a JSON config file is written to ``config/{api_name}.json``
   with empty/default values for headers, path_params, query_params, and body.
5. User edits the JSON config files to set desired values.
6. User runs ``python3 api_runner.py run auth-signin``.
7. On success, ``_handle_auth_signin_response()`` extracts tokens and writes
   ``auth.properties``.
8. ``_update_config_files_with_tokens()`` iterates all other JSON configs and
   injects the new tokens into their ``headers`` objects.

Flow 9: Interactive Menu Runner
-------------------------------

**Actors:** Terminal user, ``evercycle_api_runner.py``

1. User runs ``python3 evercycle_api_runner.py``.
2. ``EvercycleApiRunner`` loads all markdown specs.
3. A numbered menu is displayed.
4. User selects an endpoint.
5. ``prepare_api_call()`` prompts for:
   * Header values
   * Path parameter values
   * Query parameter values
   * Body parameter values (with JSON input for objects/arrays)
6. Types are coerced (number, boolean) based on the parameter type declared
   in the markdown.
7. ``ApiClient.call_endpoint()`` is invoked with the collected data.
8. Response status, headers, and body are printed to the terminal.