#pragma once

#include <stdbool.h>

#include "esp_err.h"
#include "wifi_provisioning.h"

/**
 * Which photo-fetch behavior this wake cycle should use -- normally the
 * idempotent GET /frame/image (the server decides on its own whether to
 * advance, based on its configured refresh interval, so a plain
 * wake/reboot never skips a photo just by asking), POST /frame/advance /
 * POST /frame/back to force a move in either direction (a short press of
 * the next-photo / back-photo buttons), or POST /frame/global-next /
 * POST /frame/global-back to run whatever frame-wide action (if any) is
 * configured for a held press (see next_button.h/back_button.h's
 * *_HOLD result and app/global_actions.py server-side).
 */
typedef enum {
    FETCH_NORMAL,
    FETCH_ADVANCE,
    FETCH_BACK,
    FETCH_GLOBAL_NEXT,
    FETCH_GLOBAL_BACK,
} fetch_action_t;

/**
 * Connects to the home WiFi network described by cfg, retrying up to
 * CONFIG_FRAME_STA_CONNECT_MAX_RETRIES times with a per-attempt timeout of
 * CONFIG_FRAME_STA_CONNECT_TIMEOUT_MS. Returns ESP_OK once an IP address
 * has been obtained, ESP_FAIL if all retries are exhausted.
 */
esp_err_t frame_wifi_connect_sta(const frame_config_t *cfg);

/**
 * Runs the frame's normal-operation cycle: fetch the current image from
 * cfg->toolsserver per `action` (see fetch_action_t), display it, and
 * deep-sleep until the next refresh.
 *
 * If show_management_qr is true (the manage button was held), the
 * request for that cycle carries &manage=1, and the server bakes its
 * whole manage overlay (scan-to-manage QR, battery, location/date,
 * share-QR, named face labels) directly into the image it returns --
 * see server/app/manage_overlay.py; this device is otherwise unaware
 * any of that exists, it just displays whatever comes back. Held for 30
 * seconds (the device stays awake), then reverted back to a plain fetch
 * before proceeding to the normal sleep-interval logic.
 *
 * Reads the battery (see battery_read_percent()) itself, once, after the
 * photo is already on the panel, and reports it to the server on a
 * successful fetch; a -1 reading ("no reading" -- on mains, disabled, or
 * implausible) skips the report.
 */
void frame_client_run(const frame_config_t *cfg, fetch_action_t action, bool show_management_qr);