linux-weather-bar.sh

#!/bin/bash
#
# Weather & Moon Phase Display Script
# Fetches and displays current weather information from OpenWeatherMap API
# and optionally shows moon phase during nighttime hours.
#
# EMIT_JSON_OUTPUT - Set to "true" to output JSON response (default: false)
#

# Exit on error, undefined variables, and pipe failures
set -euo pipefail

# ─── API Configuration ────────────────────────────────────────────────────────
# API keys and location are loaded from .weather_config (git-ignored)
# Config file is auto-created from .weather_config.template on first run
readonly API_BASE_URL="https://api.openweathermap.org/data/2.5"
readonly WEATHER_API_URL="${API_BASE_URL}/weather"
# Default to FREE plan (3-hourly forecast)
FORECAST_API_URL="${API_BASE_URL}/forecast"
readonly SUN_DATA_FILE="${HOME}/.cache/weather/sun-data.json"

readonly MOON_API_URL="https://astroapi.byhrast.com/moon.php"
# Path to moon data cache file
readonly MOON_DATA_FILE="${HOME}/.cache/weather/moon-data.json"
# Path to weather and forecast API response cache files
readonly WEATHER_DATA_FILE="${HOME}/.cache/weather/weather-data.json"
readonly FORECAST_DATA_FILE="${HOME}/.cache/weather/forecast-data.json"

# ─── Shared Moon Phase Data (arrays) ───────────────────────────────────────────
readonly -a MOON_PHASE_NAMES=("New Moon" "Waxing Crescent" "First Quarter" "Waxing Gibbous" "Full Moon" "Waning Gibbous" "Last Quarter" "Waning Crescent")
readonly -a MOON_PHASE_NAMES_BN=("অমাবস্যা" "শুক্লপক্ষের বাঁকা চাঁদ" "শুক্লপক্ষের অর্ধচন্দ্র" "শুক্লপক্ষের বর্ধমান চাঁদ" "পূর্ণিমা" "কৃষ্ণপক্ষের ক্ষীয়মাণ চাঁদ" "কৃষ্ণপক্ষের অর্ধচন্দ্র" "কৃষ্ণপক্ষের বাঁকা চাঁদ")
readonly -a MOON_PHASE_EMOJIS=("🌑" "🌒" "🌓" "🌔" "🌕" "🌖" "🌗" "🌘")

#######################################
# Load configuration from .weather_config or create from template
# Globals:
#   (sets API_KEY, MOON_API_KEY, LOCATION, TIMEZONE)
# Returns:
#   0 always
#######################################
load_or_create_config() {
	local script_dir config_file template_file
	script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
	config_file="${script_dir}/.weather_config"
	template_file="${script_dir}/.weather_config.template"

	if [[ -f "$config_file" ]]; then
		# Source existing config (overrides defaults)
		source "$config_file"
	elif [[ -f "$template_file" ]]; then
		# Create config from template
		cp "$template_file" "$config_file"
		source "$config_file"
	else
		# Fallback
		echo "Warning: Config file not found at $config_file" >&2
	fi
}

# Load configuration
load_or_create_config

# ─── Set Configuration Defaults (for set -u safety) ────────────────────────────
: "${API_KEY_TYPE:=FREE}"
: "${MAX_CONNECTIVITY_RETRIES:=5}"
: "${CONNECTIVITY_RETRY_DELAY:=5}"
: "${FEELS_LIKE_THRESHOLD:=5}"
: "${SHOW_RAIN_FORECAST:=true}"
: "${RAIN_FORECAST_THRESHOLD:=0.80}"
: "${RAIN_FORECAST_WINDOW:=3}"

# ─── Sunrise & Sunset ─────────────────────────────────────────────────────────
: "${SHOW_SUNRISE_SUNSET:=true}"
: "${SUNRISE_WARNING_THRESHOLD:=45}"
: "${SUNSET_WARNING_THRESHOLD:=45}"
: "${SHOW_SUNRISE_SUNSET_DURING_RAIN:=true}"
: "${SHOW_SUNRISE_SUNSET_WITH_RAIN_FORECAST:=true}"

# ─── Moonrise & Moonset ───────────────────────────────────────────────────────
: "${SHOW_MOONRISE_MOONSET:=true}"
: "${MOONRISE_WARNING_THRESHOLD:=45}"
: "${MOONSET_WARNING_THRESHOLD:=45}"
: "${SHOW_MOONRISE_MOONSET_DURING_DAYTIME:=false}"
: "${SUPPRESS_NOT_VISIBLE_MOONRISE_MOONSET:=false}"
: "${SHOW_MOONRISE_MOONSET_DURING_RAIN:=true}"
: "${SHOW_MOONRISE_MOONSET_WITH_RAIN_FORECAST:=false}"

# ─── Moon Phase ───────────────────────────────────────────────────────────────
: "${MOON_PHASE_ENABLED:=true}"
: "${MOON_DATA_CACHE_MAX_AGE:=2}"
: "${MOON_PHASE_WINDOW_START:=moonrise}"
: "${MOON_PHASE_WINDOW_DURATION:=moonset}"
: "${SHOW_MOONPHASE_DURING_DAYTIME:=false}"
: "${SUPPRESS_NOT_VISIBLE_MOONPHASE:=false}"
: "${SHOW_MOON_PHASE_DURING_RAIN:=true}"
: "${SHOW_MOON_PHASE_WITH_RAIN_FORECAST:=false}"
: "${SHOW_MOONPHASE_BENGALI:=false}"
: "${SHOW_MOONPHASE_BILINGUAL:=false}"
: "${SHOW_APSIDAL_MOON_EVENTS:=true}"
: "${SUPPRESS_NOT_VISIBLE_NIGHT_APSIDAL_MOON_EVENTS:=false}"
: "${SHOW_FULL_MOON_FOLK_NAME:=true}"

# ─── Validate Required Credentials ────────────────────────────────────────────
if [[ -z "${MOON_API_KEY:-}" ]] && [[ "${MOON_PHASE_ENABLED}" == "true" ]]; then
	echo "Warning: MOON_API_KEY not set in config; moon phase display disabled" >&2
	MOON_PHASE_ENABLED=false
fi

# ─── Adjust Forecast API based on API plan ────────────────────────────────────
# FREE plan (default) uses 3-hourly forecast (/forecast)
# PRO or other plans use hourly forecast (/forecast/hourly)
if [[ "$API_KEY_TYPE" != "FREE" ]]; then
	FORECAST_API_URL="${API_BASE_URL}/forecast/hourly"
fi

# ─── Icon Mapping ─────────────────────────────────────────────────────────────
declare -Ar WEATHER_ICONS=(
	["01d"]="☀️" ["02d"]="⛅️" ["03d"]="☁️" ["04d"]="☁️"
	["09d"]="🌧️" ["10d"]="🌦️" ["11d"]="⛈️" ["13d"]="❄️" ["50d"]="🌫️"
	["01n"]="🌕" ["02n"]="☁️" ["03n"]="☁️" ["04n"]="☁️"
	["09n"]="🌧️" ["10n"]="☔️" ["11n"]="⛈️" ["13n"]="❄️" ["50n"]="🌫️"
)

#######################################
# Check internet connectivity with retry logic
# Globals:
#   MAX_CONNECTIVITY_RETRIES
#   CONNECTIVITY_RETRY_DELAY
# Returns:
#   0 if connected, 1 otherwise
#######################################
check_connectivity() {
	local attempt connectivity

	for attempt in $(seq 1 "$MAX_CONNECTIVITY_RETRIES"); do
		if command -v nmcli &>/dev/null; then
            # nmcli failure itself should not abort — capture safely
            connectivity=$(nmcli networking connectivity check 2>/dev/null) || connectivity="none"
			if [[ "$connectivity" == "full" ]]; then
				return 0
			fi
		else
			# Fallback: try pinging a reliable server
			if ping -c 1 -W 2 8.8.8.8 &>/dev/null; then
				return 0
			fi
		fi

		if [[ $attempt -lt "$MAX_CONNECTIVITY_RETRIES" ]]; then
			sleep "$CONNECTIVITY_RETRY_DELAY"
		fi
	done

	return 1
}

#######################################
# Capitalize first letter of each word
# Arguments:
#   $1 - Input string
# Outputs:
#   Capitalized string
#######################################
capitalize_words() {
	local input="$1"
	# Using awk for better portability
	awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) tolower(substr($i,2))}1' <<<"$input"
}

#######################################
# Format temperature value
# Arguments:
#   $1 - Temperature value
# Outputs:
#   Formatted temperature (removes .0 if present)
#######################################
format_temperature() {
	local temp="$1"
	printf "%.1f" "$temp" | sed 's/\.0$//'
}

#######################################
# Get weather icon emoji
# Arguments:
#   $1 - Icon code from API
# Outputs:
#   Emoji character
#######################################
get_weather_icon() {
	local icon_code="$1"
	echo "${WEATHER_ICONS[$icon_code]:-🌡️}"
}

#######################################
# Format time
# Arguments:
#   $1 - epoch time
# Outputs:
#   Formatted time string (e.g., "6:30 PM")
#######################################
format_time() {
	local epoch="$1"
	date -d "@${epoch}" +"%-I:%M %p" 2>/dev/null ||
		date -r "$epoch" +"%-I:%M %p" 2>/dev/null
}

#######################################
# Convert a HH:MM (24-hour) time string to today's Unix epoch.
# Rejects non-time strings (e.g. "Not visible") before calling date.
# Uses GNU date with BSD date as fallback.
#
# Arguments:
#   $1 - Time string in HH:MM format
# Outputs:
#   Epoch integer on success, empty string on failure
# Returns:
#   0 always
#######################################
hhmm_to_epoch() {
	local date_str="$1"   # NEW: YYYY-MM-DD
	local hhmm="$2"

	# Validate HH:MM
	[[ "$hhmm" =~ ^[0-9]{1,2}:[0-9]{2}$ ]] || { echo "0"; return 0; }

	# Validate date
	[[ -n "$date_str" ]] || { echo "0"; return 0; }

	date -d "${date_str} ${hhmm}" +%s 2>/dev/null || \
		date -j -f "%Y-%m-%d %H:%M" "${date_str} ${hhmm}" +%s 2>/dev/null || \
		echo "0"
}

#######################################
# Fetch weather data from API
# Globals:
#   LOCATION, API_KEY, WEATHER_API_URL
# Outputs:
#   JSON response from API
# Returns:
#   0 on success, 1 on failure
#######################################
fetch_weather_data() {
	local url="${WEATHER_API_URL}?${LOCATION}&appid=${API_KEY}&units=metric"

	local response
    response=$(curl -sf "$url" 2>/dev/null) || return 1

    # Validate JSON
    echo "$response" | jq -e . >/dev/null 2>&1 || return 1

    # Persist formatted response to cache file (skip if called from another script)
    if [[ "${DISABLE_CACHE_WRITE:-false}" != "true" ]]; then
        mkdir -p "$(dirname "$WEATHER_DATA_FILE")"
        echo "$response" | jq '.' > "$WEATHER_DATA_FILE"
    fi

	echo "$response"
}

#######################################
# Parse weather data from JSON response
# Arguments:
#   $1 - JSON response
# Outputs:
#   Tab-separated values: weather_main description icon temp feels_like sunrise_epoch sunset_epoch
#######################################
parse_weather_data() {
	local response="$1"

	jq -re '[
        .weather[0].main // "",
		.weather[0].description // "",
        .weather[0].icon // "",
        .main.temp // 0,
        .main.feels_like // 0,
		.sys.sunrise // 0,
        .sys.sunset // 0
    ] | @tsv' <<<"$response"
}

save_sun_data() {
    local sunrise_epoch="$1"
    local sunset_epoch="$2"
    local now
    now=$(date +%s)
    # Only save during daytime — overnight the API returns tomorrow's values
    # and we need yesterday's sunset to remain in cache
    # Guard both sunrise AND sunset to prevent corrupted cache
    (( sunrise_epoch > 0 && sunset_epoch > 0 && now >= sunrise_epoch )) || return 0
    
    local today cached_date
    today=$(date +"%d/%m/%Y")
    
    # Check if file already contains today's data — don't overwrite
    if [[ -f "$SUN_DATA_FILE" ]]; then
        cached_date=$(jq -r '.date // ""' <"$SUN_DATA_FILE" 2>/dev/null) || cached_date=""
        if [[ "$cached_date" == "$today" ]]; then
            # Cache already has today's data, no need to refresh
            return 0
        fi
    fi
    
    mkdir -p "$(dirname "$SUN_DATA_FILE")"
    jq -n \
        --arg date "$today" \
        --argjson sunrise "$sunrise_epoch" \
        --argjson sunset "$sunset_epoch" \
        '{date: $date, sunrise: $sunrise, sunset: $sunset}' > "$SUN_DATA_FILE"
}

#######################################
# Resolve the effective sunrise for the solar window ceiling.
# During evening/night (after today's sunrise), the relevant sunrise
# is TOMORROW's, not today's. Add 86400 seconds to get it.
#
# Arguments:
#   $1 - api_sunrise_epoch (today's sunrise from API)
# Outputs:
#   Epoch of the next sunrise (tomorrow's if we're past today's)
#######################################
get_effective_sunrise() {
    local api_sunrise_epoch="$1"
    local now
    now=$(date +%s)
    # If we're past today's sunrise, the next sunrise is tomorrow's
    if (( now >= api_sunrise_epoch )); then
        echo $(( api_sunrise_epoch + 86400 ))
    else
        echo "$api_sunrise_epoch"
    fi
}

#######################################
# Determine the effective sunset to use for the Solar Window.
#
# Context:
# - Before midnight (daytime/evening): use TODAY's sunset from API
# - After midnight (overnight): use YESTERDAY's sunset from cache
#
# Logic:
# If current time is past today's sunrise, we're in "today's" timeframe (daytime/evening).
# Use today's sunset directly.
#
# If current time is before today's sunrise, we're in "overnight" (yesterday's sunset → today's sunrise).
# Fetch the cache and use yesterday's sunset from there.
#
# If cache is missing/stale and we're overnight:
# Estimate yesterday's sunset as (api_sunrise_epoch - 24h).
# This typically differs by ~3min from reality but is acceptable.
#
# Arguments:
#   $1 - api_sunset_epoch (today's sunset from API)
#   $2 - api_sunrise_epoch (today's sunrise from API)
# Outputs:
#   Epoch of the sunset to use for the Solar Window
# Returns:
#   0 always
#######################################
get_effective_sunset() {
    local api_sunset_epoch="$1"
    local api_sunrise_epoch="$2"
    local now
    now=$(date +%s)

    # If we're past today's sunrise, it's daytime/evening — use API sunset as-is
    if (( now >= api_sunrise_epoch )); then
        echo "$api_sunset_epoch"
        return 0
    fi

    # Overnight: try yesterday's sunset from cache
    if [[ -f "$SUN_DATA_FILE" ]]; then
        local cached_sunset
        cached_sunset=$(jq -r '.sunset // 0' <"$SUN_DATA_FILE" 2>/dev/null)
        if (( cached_sunset > 0 )); then
            echo "$cached_sunset"
            return 0
        fi
    fi

    # Cache missing/stale — estimate yesterday's sunset from today's sunrise
    # Sunset is typically ~12.5 hours after sunrise; this error is acceptable
    echo $(( api_sunrise_epoch - 43200 ))
}

#######################################
# Fetch forecast data from API
# Globals:
#   LOCATION, API_KEY, FORECAST_API_URL
# Outputs:
#   JSON response
# Returns:
#   0 on success, 1 on failure
#######################################
fetch_forecast_data() {
	local url="${FORECAST_API_URL}?${LOCATION}&appid=${API_KEY}&units=metric"
	local response
	response=$(curl -sf "$url" 2>/dev/null) || return 1

    echo "$response" | jq -e . >/dev/null 2>&1 || return 1

    # Persist formatted response to cache file (skip if called from another script)
    if [[ "${DISABLE_CACHE_WRITE:-false}" != "true" ]]; then
        mkdir -p "$(dirname "$FORECAST_DATA_FILE")"
        echo "$response" | jq '.' > "$FORECAST_DATA_FILE"
    fi

    echo "$response"
}

#######################################
# Get next rain timing and probability
# within RAIN_FORECAST_WINDOW
# Arguments:
#   $1 - JSON forecast response
# Outputs:
#   "rain_epoch probability" OR empty
#######################################
get_rain_forecast() {
	local response="$1"
    local result

    result=$(jq -r \
		--argjson threshold "$RAIN_FORECAST_THRESHOLD" \
		--argjson window "$((RAIN_FORECAST_WINDOW * 3600))" '
		now as $now
		| .list
		| map(
			select(
				(.dt - $now) <= $window and
				(.pop >= $threshold)
			)
		)
		| if length == 0 then
			empty
		  else
			.[0] as $first
            | [$first.dt, ($first.pop * 100 | floor), ($first.weather[0].description // ""), ($first.weather[0].icon // "") ]
			| @tsv
		  end
	' <<<"$response" 2>/dev/null) || return 1

    # empty output is valid (no rain forecast) — not an error
    echo "$result"
}

#######################################
# Format rain warning text
# Arguments:
#   $1 - Rain epoch time
#   $2 - Probability %
#   $3 - Description string
#   $4 - Icon emoji
# Outputs:
#   Formatted rain warning string
#######################################
format_rain_warning() {
	local rain_epoch="$1"
	local probability="$2"
	local description="$3"
	local icon="$4"

	# Convert to local time string (e.g., 6:45 PM)
	local rain_time
	rain_time=$(format_time "$rain_epoch")
	if [[ -z "$rain_time" ]]; then
    	rain_time="soon"   # graceful degradation
	fi

    # 24h threshold logic
    local now rain_date_fmt=""
    now=$(date +%s)

    if (( rain_epoch - now > 86400 )); then
        rain_date_fmt=$(date -d "@${rain_epoch}" +"%-d %B" 2>/dev/null || date -r "$rain_epoch" +"%-d %B")
    fi

    # Description normalization
	local rain_desc
	if [[ "$description" =~ [Rr]ain|[Dd]rizzle|[Tt]hunderstorm ]]; then
		rain_desc=$(capitalize_words "$description")
	else
		rain_desc="Rain likely"
		icon="🌧️"
	fi

    # Build output
    if [[ -n "$rain_date_fmt" ]]; then
        echo "${icon}  ${rain_desc} ≈ ${rain_date_fmt} ${rain_time^^} (${probability}%)"
    else
        echo "${icon}  ${rain_desc} ≈ ${rain_time^^} (${probability}%)"
    fi
}

#######################################
# Validate a moon-data JSON string for structural correctness.
#
# Checks:
#   - Non-empty string
#   - Parses as valid JSON
#   - .moonrise is a JSON number (not a string, null, or other non-numeric value)
#   - .moonset  is a JSON number (not a string, null, or other non-numeric value)
#
# Note: zero is accepted as a valid number (moon not visible today);
# type("number") is the contract — downstream callers decide what to do
# with the actual value.
#
# Arguments:
#   $1 - JSON string to validate
# Returns:
#   0 (true)  if valid
#   1 (false) if empty, unparseable, or moonrise/moonset are not numbers
#######################################
validate_moon_json() {
	local json="$1"
	[[ -n "$json" ]] || return 1
	jq -e '
		(.moonrise | type) == "number" and
		(.moonset  | type) == "number"
	' <<<"$json" >/dev/null 2>&1
}

#######################################
# Load moon data cache from MOON_DATA_FILE.
# Creates the cache directory and an empty JSON object if absent.
# If the file exists but contains corrupt data (e.g. moonrise/moonset
# are non-numeric), the file is reset to "{}" and a warning is emitted.
#
# Globals:
#   MOON_DATA_FILE
# Arguments:
#   (none)
# Outputs:
#   Cached JSON string, or "{}" if file did not exist or was corrupt
# Returns:
#   0 always
#######################################
load_moon_cache() {
	mkdir -p "$(dirname "$MOON_DATA_FILE")"
	if [[ ! -f "$MOON_DATA_FILE" ]]; then
		echo "{}" > "$MOON_DATA_FILE"
		echo "{}"
		return 0
	fi

	local cache
	cache=$(cat "$MOON_DATA_FILE")

	# Accept empty placeholder "{}" without running full field validation
	if [[ "$cache" == "{}" ]]; then
		echo "{}"
		return 0
	fi

	if ! validate_moon_json "$cache"; then
		# echo "Warning: moon-data.json is corrupt (moonrise/moonset must be numbers); resetting cache" >&2
		echo "{}" > "$MOON_DATA_FILE"
		echo "{}"
		return 0
	fi

	echo "$cache"
}

# -----------------------------------------------------------------------------
# call_moon_api
#
# Purpose:
#   Calls the configured Moon API endpoint and returns validated JSON output.
#
# Inputs:
#   $1 - date_param (required)
#   $2 - time_param (required)
#
# Behavior:
#   - Builds a request URL using:
#       MOON_API_URL, MOON_API_KEY, LOCATION, TIMEZONE
#   - Sends a GET request via curl
#   - Ensures request succeeds (non-zero exit → failure)
#   - Validates that response contains expected field: ".moonrise"
#   - Adds an additional field:
#       retrieved_at → current system date-time (ISO-8601 format)
#   - Returns the modified JSON response
#
# Output:
#   JSON response from API with added fields:
#     {
#       ... original fields ...,
#       "retrieved_at": "1745207588",
#       "moonrise": 1745207940,
#       "moonset": 1745234100
#     }
#
# Failure cases:
#   - Missing input parameters → return 1
#   - curl failure → return 1
#   - invalid or unexpected JSON → return 1
# -----------------------------------------------------------------------------
call_moon_api() {
    local date_param="$1"
    local time_param="$2"
    local url response

    # Validate inputs
    [ -z "$date_param" ] && return 1
    [ -z "$time_param" ] && return 1

    url="${MOON_API_URL}?key=${MOON_API_KEY}&${LOCATION}&tz=${TIMEZONE}&date=${date_param}&time=${time_param}"
    
    response=$(curl -sf "$url" 2>/dev/null) || return 1

    # Sanity-check: ensure expected field is present
    echo "$response" | jq -e '.moonrise' >/dev/null 2>&1 || return 1

    # Convert all values to strings (epochs are injected afterwards as plain integers)
    response=$(echo "$response" | jq 'walk(if type == "number" or type == "boolean" then tostring else . end)')

    # ── Replace HH:MM strings with epoch integers ─────────────────────────────
    # moonrise: always anchored to the response date.
    # moonset:  same date normally; next day when moonset HH:MM < moonrise HH:MM
    #           (midnight crossing).
    local api_date moonrise_hhmm moonset_hhmm
    api_date=$(echo "$response"      | jq -r '.date     // ""')
    moonrise_hhmm=$(echo "$response" | jq -r '.moonrise // ""')
    moonset_hhmm=$(echo "$response"  | jq -r '.moonset  // ""')

    local norm_date norm_date_next moonrise_ep moonset_ep
    norm_date=""
    norm_date_next=""
    moonrise_ep=0
    moonset_ep=0

    if [[ "$api_date" =~ ^[0-9]{2}/[0-9]{2}/[0-9]{4}$ ]]; then
        norm_date=$(date -d "$(echo "$api_date" | awk -F/ '{print $3"-"$2"-"$1}')" +"%Y-%m-%d" 2>/dev/null)
        norm_date_next=$(date -d "$norm_date + 1 day" +"%Y-%m-%d" 2>/dev/null)
    fi

    if [[ -n "$norm_date" ]]; then
        moonrise_ep=$(hhmm_to_epoch "$norm_date" "$moonrise_hhmm")
        moonrise_ep=${moonrise_ep:-0}

        # Determine which date moonset belongs to:
        # if moonset HH:MM < moonrise HH:MM → moonset is next calendar day
        local moonset_date="$norm_date"
        if [[ "$moonrise_hhmm" =~ ^[0-9]{1,2}:[0-9]{2}$ ]] && \
           [[ "$moonset_hhmm"  =~ ^[0-9]{1,2}:[0-9]{2}$ ]]; then
            local rise_mins set_mins
            rise_mins=$(echo "$moonrise_hhmm" | awk -F: '{print $1*60+$2}')
            set_mins=$(echo  "$moonset_hhmm"  | awk -F: '{print $1*60+$2}')
            if (( set_mins < rise_mins )) && [[ -n "$norm_date_next" ]]; then
                moonset_date="$norm_date_next"
            fi
        fi

        moonset_ep=$(hhmm_to_epoch "$moonset_date" "$moonset_hhmm")
        moonset_ep=${moonset_ep:-0}
    fi

    # Write epochs back into .moonrise / .moonset / .retrieved_at as plain integers
    response=$(echo "$response" | jq \
        --argjson mrise "$moonrise_ep" \
        --argjson mset  "$moonset_ep" \
        --argjson ts    "$(date +%s)" \
        '.moonrise = $mrise | .moonset = $mset | .retrieved_at = $ts')

    echo "$response"
}

#######################################
# Fetch fresh moon data from astroapi and return validated JSON.
#
# Globals:
#   MOON_API_KEY, MOON_API_URL, LOCATION, TIMEZONE
# Arguments:
#   $1 - needed_date in DD/MM/YYYY format
# Outputs:
#   Fresh JSON string on success, nothing on failure
# Returns:
#   0 on success, 1 on failure
#######################################
fetch_moon_data() {
    local needed_date="$1"
    local time_param
    time_param=$(date +"%H:%M")
    call_moon_api "$needed_date" "$time_param"
}

#######################################
# Write validated moon data to cache file.
# Only writes if the fetched date matches the needed date
# and the JSON passes structural validation (moonrise/moonset are numbers).
#
# Arguments:
#   $1 - fresh moon data JSON
#   $2 - needed_date (DD/MM/YYYY)
# Returns:
#   0 always
#######################################
_save_moon_cache() {
    local data="$1"
    local needed_date="$2"
    local fetched_date
    fetched_date=$(jq -r '.date // ""' <<<"$data" 2>/dev/null)
    [[ "$fetched_date" == "$needed_date" ]] || return 0

    # Refuse to persist structurally invalid data
    if ! validate_moon_json "$data"; then
        # echo "Warning: refusing to cache moon data — moonrise/moonset are not numbers" >&2
        return 0
    fi

    # Skip saving if called from another script
    if [[ "${DISABLE_CACHE_WRITE:-false}" != "true" ]]; then
        mkdir -p "$(dirname "$MOON_DATA_FILE")"
        printf '%s\n' "$data" | jq '.' > "$MOON_DATA_FILE"
    fi
}

#######################################
# Determine whether a date-matched moon cache entry needs refreshing.
#
# A cache is stale when both of the following are true:
#   - We are inside the active lunar window (past window_start, before window_end)
#     (using inferred window if any rise/set data is missing)
# AND either:
#   a) The cache was fetched before the window start (position/illumination stale), OR
#   b) The cache has exceeded MOON_DATA_CACHE_MAX_AGE since retrieval
#
# The inferred window is used instead of requiring both moonrise and moonset,
# ensuring cache freshness even when partial lunar data is returned.
#
# Arguments:
#   $1 - cache JSON string
#   $2 - now (epoch)
#   $3 - cached_moonrise_epoch (from cache; 0 if unknown/invalid)
#   $4 - cached_moonset_epoch  (from cache; 0 if unknown/invalid)
# Returns:
#   0 (true)  if stale
#   1 (false) if fresh or indeterminate
#######################################
_is_moon_cache_stale() {
    local cache="$1"
    local now="$2"
    local cached_moonrise_epoch="${3:-0}"
    local cached_moonset_epoch="${4:-0}"

    local retrieved_at_epoch=0
    retrieved_at_epoch=$(jq -r '.retrieved_at // 0' <<<"$cache" 2>/dev/null)
    retrieved_at_epoch=${retrieved_at_epoch:-0}

    # Cannot determine staleness without fetch timestamp
    (( retrieved_at_epoch > 0 )) || return 1

    # Get effective lunar window (actual or inferred from partial data)
    local window_start window_end
    IFS=$'\t' read -r window_start window_end \
        <<<"$(get_effective_lunar_window "$cached_moonrise_epoch" "$cached_moonset_epoch")"

    # Cannot determine staleness without valid window bounds
    (( window_start > 0 && window_end > 0 )) || return 1

    # Only check staleness inside the active lunar window
    (( now >= window_start )) || return 1
    (( now < window_end )) || return 1

    # (a) Fetched before window start — position/illumination data is stale
    if (( retrieved_at_epoch < window_start )); then
        return 0
    fi

    # (b) Older than configured max age while still inside lunar window
    local max_age_seconds=$(( MOON_DATA_CACHE_MAX_AGE * 3600 ))
    if (( now - retrieved_at_epoch > max_age_seconds )); then
        return 0
    fi

    return 1  # fresh
}

#######################################
# Return current moon data — from cache if valid, otherwise fetched live.
#
# Date selection logic:
#   If the cached moonset epoch is still in the future, the active lunar
#   cycle belongs to whatever date the cache holds (today or yesterday for
#   overnight midnight-crossings). Once moonset has passed, today's data
#   is needed. This single rule replaces all explicit sunrise/overnight
#   checks that were previously required.
#
# Cache validation:
#   When the cached date matches needed_date, staleness is checked via
#   _is_moon_cache_stale. Fresh cache is returned immediately; stale cache
#   triggers a targeted re-fetch for needed_date.
#
# Fallback:
#   On fetch failure the existing cache is returned as-is (graceful
#   degradation). If no cache exists at all an empty string is returned.
#
# Globals:
#   MOON_DATA_FILE, MOON_API_URL, MOON_API_KEY, LOCATION, TIMEZONE,
#   MOON_DATA_CACHE_MAX_AGE
# Arguments:
#   (none)
# Outputs:
#   JSON string, or empty string on total failure
# Returns:
#   0 always
#######################################
get_moon_data() {
    local cache now today needed_date cached_date cached_moonrise_epoch cached_moonset_epoch

    cache=$(load_moon_cache)
    now=$(date +%s)
    today=$(date +"%d/%m/%Y")

    cached_date=$(jq -r '.date // ""' <<<"$cache" 2>/dev/null) || cached_date=""
    cached_moonrise_epoch=$(jq -r '.moonrise // 0' <<<"$cache" 2>/dev/null)
    cached_moonrise_epoch=${cached_moonrise_epoch:-0}
    cached_moonset_epoch=$(jq -r '.moonset // 0' <<<"$cache" 2>/dev/null)
    cached_moonset_epoch=${cached_moonset_epoch:-0}

    # Determine needed date:
    # Active lunar cycle → keep the date the cache already holds (today or yesterday).
    # Uses inferred window when data is partial, maintaining cache validity.
    # Moonset past (or no usable cache) → need today's data.
    local cache_window_end
    cache_window_end=$(cut -d$'\t' -f2 <<< "$(get_effective_lunar_window "$cached_moonrise_epoch" "$cached_moonset_epoch")")
    
    if [[ -n "$cached_date" ]] && (( cache_window_end > 0 && cache_window_end > now )); then
        needed_date="$cached_date"
    else
        needed_date="$today"
    fi

    # Cache hit: date matches — return immediately or refresh if stale
    if [[ "$cached_date" == "$needed_date" ]]; then
        if ! _is_moon_cache_stale "$cache" "$now" "$cached_moonrise_epoch" "$cached_moonset_epoch"; then
            echo "$cache"
            return 0
        fi

        # Stale — fetch fresh; fall back to existing cache on failure
        local fresh
        fresh=$(fetch_moon_data "$needed_date") || true
        if [[ -n "$fresh" ]]; then
            _save_moon_cache "$fresh" "$needed_date"
            echo "$fresh"
            return 0
        fi

        echo "$cache"
        return 0
    fi

    # Cache miss or wrong date — fetch fresh data for needed_date
    local fresh
    fresh=$(fetch_moon_data "$needed_date") || true

    if [[ -n "$fresh" ]]; then
        _save_moon_cache "$fresh" "$needed_date"
        echo "$fresh"
        return 0
    fi

    # Complete failure — return existing cache or empty string
    if [[ -n "$cache" && "$cache" != "{}" ]]; then
        echo "$cache"
        return 0
    fi

    echo ""
}

#######################################
# Parse moonrise and moonset HH:MM strings from moon data JSON
# and return the epoch integers stored in .moonrise / .moonset.
#
# Epochs are computed by call_moon_api at fetch time and stored directly
# in .moonrise and .moonset, replacing the original HH:MM strings:
#   .moonrise — epoch anchored to the API response date
#   .moonset  — epoch on same date, or next day if moonset HH:MM
#               < moonrise HH:MM (midnight crossing already resolved)
#
# Arguments:
#   $1 - Moon data JSON string
#   $2 - (unused, kept for call-site compatibility)
# Outputs:
#   Tab-separated: moonrise_epoch (from .moonrise)<TAB>moonset_epoch (from .moonset)
# Returns:
#   0 always
#######################################
parse_moon_times() {
    local moon_data="$1"
    # $2 (sunrise_epoch) kept in signature for call-site compatibility — not needed
    # now that epochs are pre-computed and stored in the JSON.

    local moonrise_epoch moonset_epoch
    moonrise_epoch=$(jq -r '.moonrise // 0' <<<"$moon_data" 2>/dev/null)
    moonset_epoch=$(jq  -r '.moonset  // 0' <<<"$moon_data" 2>/dev/null)

    moonrise_epoch=${moonrise_epoch:-0}
    moonset_epoch=${moonset_epoch:-0}

    printf "%s\t%s\n" "$moonrise_epoch" "$moonset_epoch"
}

#######################################
# Check if moon data JSON contains valid moon times (strict validation).
# Ensures times match HH:MM format, rejecting "Not visible" and other invalid strings.
#
# Arguments:
#   $1 - Moon data JSON string
# Returns:
#   0 (true)  if has valid moonrise or moonset in HH:MM format
#   1 (false) if empty, missing both fields, or contains invalid strings
#######################################
is_valid_moon_data() {
	local moon_data="$1"
	[[ -n "$moon_data" ]] || return 1
	# Valid if at least one pre-computed epoch is a positive integer
	jq -e '(
			((.moonrise // 0) | type == "number" and . > 0) or
			((.moonset  // 0) | type == "number" and . > 0)
	)' <<<"$moon_data" >/dev/null 2>&1
}

#######################################
# Resolve the moon phase index (0-7) from API data.
# Only returns valid index if API provides recognized phase name.
# Returns nothing if API data missing or phase unrecognized.
#
# Arguments:
#   $1 - Moon data JSON string (may be empty)
# Outputs:
#   Integer index 0-7, or nothing if not available from API
# Returns:
#   0 always
#######################################
resolve_phase_index() {
	local moon_data="$1"

	[[ -z "$moon_data" ]] && return 0

	local api_phase
	api_phase=$(jq -r '.phase // ""' <<<"$moon_data" 2>/dev/null)

	[[ -z "$api_phase" ]] && return 0

	local i
	for i in "${!MOON_PHASE_NAMES[@]}"; do
		if [[ "${MOON_PHASE_NAMES[i],,}" == "${api_phase,,}" ]]; then
			echo "$i"
			return 0
		fi
	done
}
#######################################
# Format and return the moon phase string for display.
#
# Globals:
#   SHOW_MOONPHASE_BENGALI   - true → Bengali only
#   SHOW_MOONPHASE_BILINGUAL - true → English + Bengali (overrides BENGALI)
#   MOON_PHASE_EMOJIS, MOON_PHASE_NAMES, MOON_PHASE_NAMES_BN
#   SHOW_FULL_MOON_FOLK_NAME - true → replace "Full Moon" with folk name
# Arguments:
#   $1 - Phase index (0-7)
#   $2 - Apsidal syzygy label (optional, e.g. "Supermoon", "Micromoon")
#        When provided and non-empty, appended as "(label)" after the phase name.
#        In bilingual mode it is always appended in English after the Bengali name.
#   $3 - Moonrise epoch (optional, 0 if unknown; used for folk name lookup)
# Outputs:
#   English:    "🌕  Flower Moon"          or  "🌕  Flower Moon (Supermoon)"
#   Bengali:    "🌕  পূর্ণিমা"           or  "🌕  পূর্ণিমা (Supermoon)"
#   Bilingual:  "🌕  Flower Moon (পূর্ণিমা)" or  "🌕  Flower Moon (পূর্ণিমা) (Supermoon)"
# Returns:
#   0 always
#######################################
get_moon_phase() {
	local phase_index="$1"
	local syzygy_label="${2:-}"
	local moon_data="${3:-}"

	# For Full Moon (phase_index == 4), resolve the English label using folk name if applicable.
	local english_label="${MOON_PHASE_NAMES[$phase_index]}"
	if (( phase_index == 4 )); then
		english_label=$(resolve_full_moon_label "Full Moon" "$moon_data")
	fi

	local base
	if [[ "$SHOW_MOONPHASE_BILINGUAL" == "true" ]]; then
		base="${MOON_PHASE_EMOJIS[$phase_index]}  ${english_label} (${MOON_PHASE_NAMES_BN[$phase_index]})"
	elif [[ "$SHOW_MOONPHASE_BENGALI" == "true" ]]; then
		base="${MOON_PHASE_EMOJIS[$phase_index]}  ${MOON_PHASE_NAMES_BN[$phase_index]}"
	else
		base="${MOON_PHASE_EMOJIS[$phase_index]}  ${english_label}"
	fi

	if [[ -n "$syzygy_label" ]]; then
		echo "${base} (${syzygy_label})"
	else
		echo "$base"
	fi
}

#######################################
# Extract illumination percentage as a plain number (no % sign).
#
# Arguments:
#   $1 - Moon data JSON string
# Outputs:
#   Numeric string (e.g. "5.0"), or empty on failure
# Returns:
#   0 always
#######################################
parse_illumination_pct() {
	local moon_data="$1"
	jq -r '.illumination // ""' <<<"$moon_data" 2>/dev/null | tr -d '%'
}

# Determine whether the moon is too dim to be considered visible
# based on its illumination percentage.
#
# Args:
#   $1 - illumination_pct (numeric, e.g., 2.5 for 2.5%)
#
# Returns:
#   0 (true)  - if illumination is below visibility threshold (< 5.0%)
#   1 (false) - if illumination is sufficient for visibility
#
# Notes:
#   - Returns false if input is empty or invalid
#   - Threshold (5.0%) can be adjusted based on desired sensitivity
is_moon_too_dim() {
	local illumination_pct="$1"

	# Return false if empty (can't decide)
	[[ -z "$illumination_pct" ]] && return 1

	awk -v i="$illumination_pct" 'BEGIN { exit (i < 5.0 ? 0 : 1) }'
}

#######################################
# Determine whether the moon is visible during nighttime hours.
#
# Night is defined as the window [effective_sunset → effective_sunrise].
# The moon is visible at night if its arc overlaps that window:
#   moonset  > effective_sunset   (still up when night begins)
#   moonrise < effective_sunrise  (rises before daylight returns)
#
# A moon is considered "not visible at night" if ANY condition is true:
#
#   1. Illumination < 5% — moon is too close to the sun to observe
#      (reliably catches New Moon regardless of rise/set times).
#      Short-circuits: condition 2 is never evaluated when this is true.
#
#   2. moonset  <= effective_sunset  — moon already gone before night begins
#      OR
#      moonrise >= effective_sunrise — moon won't rise until daytime
#      Either bound violated means no overlap with the night window.
#
# Using effective_sunrise (tomorrow's if past today's) rather than raw
# sunrise correctly handles overnight scenarios where moonrise occurs
# after midnight but before dawn.
#
# Arguments:
#   $1 - moonrise_epoch          (0 if unknown)
#   $2 - moonset_epoch           (0 if unknown)
#   $3 - effective_sunset_epoch  (yesterday's if overnight, today's otherwise)
#   $4 - effective_sunrise_epoch (tomorrow's if past today's sunrise)
#   $5 - illumination_pct        (numeric, e.g. 2.4 — no % sign)
# Outputs:
#   (none)
# Returns:
#   0 (true)  if moon IS visible during nighttime (show syzygy label)
#   1 (false) if moon is NOT visible at night (suppress syzygy label)
#######################################
is_moon_visible_at_night() {
	local moonrise_epoch="$1"
	local moonset_epoch="$2"
	local effective_sunset_epoch="$3"
	local effective_sunrise_epoch="$4"
	local illumination_pct="$5"

	# Condition 1: illumination too low — short-circuit
	if is_moon_too_dim "$illumination_pct"; then
		return 1
	fi

	# Condition 2: moon's arc must overlap the night window [effective_sunset → effective_sunrise]
	# Unknown times → assume visible (don't suppress)
	(( moonrise_epoch > 0 && moonset_epoch > 0 && effective_sunset_epoch > 0 && effective_sunrise_epoch > 0 )) || return 0

	if (( moonset_epoch <= effective_sunset_epoch || moonrise_epoch >= effective_sunrise_epoch )); then
		return 1  # no overlap with night window
	fi

	return 0
}
#######################################
# Compute an apsidal syzygy label for the current moon, if applicable.
#
# Distance thresholds (mutually exclusive):
#   Supermoon / Super New Moon – distance ≤ 367 600 km
#   Micromoon                  – distance ≥ 401 000 km
#
# When SUPPRESS_NOT_VISIBLE_NIGHT_APSIDAL_MOON_EVENTS is true, the label is
# suppressed if the moon is not visible during nighttime hours — either
# because illumination is below 5% (lost in solar glare) or because
# the moon's arc does not overlap the night window [effective_sunset →
# effective_sunrise]. This will typically suppress Super New Moon labels
# since New Moons are near-solar and always have near-zero illumination.
#
# NOTE: Folk moon names (Flower Moon, Wolf Moon, etc.) are handled separately
# by resolve_full_moon_label() and are INDEPENDENT of apsidal events.
# This function returns ONLY the apsidal label.
#
# Arguments:
#   $1 - Moon data JSON string
#   $2 - moonrise_epoch          (from parse_moon_times; 0 if unknown)
#   $3 - moonset_epoch           (from parse_moon_times; 0 if unknown)
#   $4 - effective_sunset_epoch  (yesterday's if overnight, today's otherwise)
#   $5 - effective_sunrise_epoch (tomorrow's if past today's sunrise)
# Outputs:
#   "Super New Moon" (supermoon during New Moon phase)
#   "Supermoon"      (supermoon during Full Moon phase)
#   "Micromoon"      (micromoon during either phase)
#   Empty string if none applies, feature disabled, or visibility suppressed
# Returns:
#   0 always
#######################################

# Traditional full moon folk names by month (Algonquin / Farmer's Almanac)
declare -A FULL_MOON_FOLK_NAMES=(
	[1]="Wolf Moon"
	[2]="Snow Moon"
	[3]="Worm Moon"
	[4]="Pink Moon"
	[5]="Flower Moon"
	[6]="Strawberry Moon"
	[7]="Buck Moon"
	[8]="Sturgeon Moon"
	[9]="Harvest Moon"   # Approximation: strictly the full moon nearest the autumn equinox
	[10]="Hunter's Moon"
	[11]="Beaver Moon"
	[12]="Cold Moon"
)

#######################################
# Resolve the appropriate Full Moon label: either a traditional folk name
# or the generic "Full Moon" label.
#
# This function is INDEPENDENT of apsidal events and SHOW_APSIDAL_MOON_EVENTS.
# It returns the base label that should be used for Full Moon phases.
#
# Month is extracted solely from the .date field (DD/MM/YYYY) in moon_data —
# the canonical API date, always present regardless of moonrise/moonset values.
#
# Arguments:
#   $1 - Phase name (e.g., "Full Moon", "New Moon", "Waxing Gibbous")
#   $2 - Moon data JSON string
# Outputs:
#   "Full Moon" (default)
#   Traditional folk name (e.g., "Flower Moon") if SHOW_FULL_MOON_FOLK_NAME is true
# Returns:
#   0 always
#######################################
resolve_full_moon_label() {
	local phase="$1"
	local moon_data="${2:-}"

	# Only apply folk names to Full Moon phases
	[[ "$phase" == "Full Moon" ]] || { echo "Full Moon"; return 0; }

	# Check if folk name feature is enabled
	[[ "$SHOW_FULL_MOON_FOLK_NAME" == "true" ]] || { echo "Full Moon"; return 0; }

	# Extract month from .date field (DD/MM/YYYY)
	local api_date month=""
	api_date=$(jq -r '.date // ""' <<<"$moon_data" 2>/dev/null)
	if [[ "$api_date" =~ ^[0-9]{2}/([0-9]{2})/[0-9]{4}$ ]]; then
		month="${BASH_REMATCH[1]#0}"   # strip leading zero (e.g. "05" → "5")
	fi

	# Look up folk name for this month
	local folk_name="${FULL_MOON_FOLK_NAMES[$month]:-}"
	if [[ -n "$folk_name" ]]; then
		echo "$folk_name"
	else
		echo "Full Moon"
	fi
}

get_lunar_apsidal_syzygy() {
	local moon_data="$1"
	local moonrise_epoch="${2:-0}"
	local moonset_epoch="${3:-0}"
	local effective_sunset_epoch="${4:-0}"
	local effective_sunrise_epoch="${5:-0}"

	[[ "$SHOW_APSIDAL_MOON_EVENTS" == "true" ]] || return 0
	[[ -n "$moon_data" ]] || return 0

	local phase distance_km illumination_pct
	phase=$(jq -r '.phase // ""' <<<"$moon_data" 2>/dev/null)
	distance_km=$(jq -r '.position.distance // ""' <<<"$moon_data" 2>/dev/null)
	illumination_pct=$(parse_illumination_pct "$moon_data")

	# Must be New Moon or Full Moon
	[[ "$phase" == "New Moon" || "$phase" == "Full Moon" ]] || return 0

	# Must have a parseable distance
	[[ -n "$distance_km" ]] || return 0

	# ── Night visibility gate ──────────────────────────────────────────────────
	if [[ "$SUPPRESS_NOT_VISIBLE_NIGHT_APSIDAL_MOON_EVENTS" == "true" ]]; then
		if ! is_moon_visible_at_night \
				"$moonrise_epoch" "$moonset_epoch" \
				"$effective_sunset_epoch" "$effective_sunrise_epoch" \
				"$illumination_pct"; then
			return 0  # moon not visible at night — suppress label
		fi
	fi

	local is_supermoon is_micromoon
	is_supermoon=$(awk -v d="$distance_km" 'BEGIN { print (d <= 367600) ? "true" : "false" }')
	is_micromoon=$(awk -v d="$distance_km" 'BEGIN { print (d >= 401000) ? "true" : "false" }')

	# ── Resolve apsidal label ──────────────────────────────────────────────────
	local apsidal_label=""
	if [[ "$is_supermoon" == "true" ]]; then
		if [[ "$phase" == "New Moon" ]]; then
			apsidal_label="Super New Moon"
		else
			apsidal_label="Supermoon"
		fi
	elif [[ "$is_micromoon" == "true" ]]; then
		apsidal_label="Micromoon"
	fi

	# Return apsidal label (may be empty if no apsidal event detected)
	echo "$apsidal_label"
}

#######################################
# Resolve window start epoch from MOON_PHASE_WINDOW_START parameter.
#
# IMPORTANT: $3 must be lunar_window_start from get_effective_lunar_window,
# NOT the raw moonrise_epoch from the API.  By the time this function is called,
# infer_lunar_window_bounds has already resolved any missing moonrise into a
# best-estimate start (moonset - 12h 25m).  Passing that inferred value here
# keeps inference logic in one place (DRY) and guarantees a valid anchor in
# every case without a second, inconsistent fallback path.
#
# When param is "moonrise":
#   Use lunar_window_start directly (actual or inferred moonrise).
#   Independent of SHOW_MOONPHASE_DURING_DAYTIME.
#
# When param is an integer (minutes):
#   The anchor depends on SHOW_MOONPHASE_DURING_DAYTIME:
#     true  → delay measured from lunar_window_start (moonrise or its inference)
#     false → delay measured from sunset_epoch
#
# Arguments:
#   $1 - MOON_PHASE_WINDOW_START value ("moonrise" or a non-negative integer)
#   $2 - sunset_epoch        (effective sunset; used when daytime display is off)
#   $3 - lunar_window_start  (from get_effective_lunar_window — real or inferred moonrise)
#   $4 - show_during_daytime ("true"/"false") — controls integer anchor selection
# Outputs:
#   Window start epoch (integer)
# Returns:
#   0 always
#######################################
resolve_window_start() {
	local param="$1"
	local sunset_epoch="$2"
	local lunar_window_start="$3"
	local show_during_daytime="$4"

	if [[ "$param" == "moonrise" ]]; then
		# Keyword mode: always anchor to (inferred) moonrise
		echo "$lunar_window_start"
	else
		# Numeric mode: choose anchor based on daytime display preference
		local anchor
		if [[ "$show_during_daytime" == "true" ]]; then
			anchor="$lunar_window_start"
		else
			anchor="$sunset_epoch"
		fi
		echo $(( anchor + ${param:-1} * 60 ))
	fi
}

#######################################
# Resolve window end epoch from MOON_PHASE_WINDOW_DURATION parameter.
# Supports: numeric (minutes after start) or "moonset" (use moonset directly)
#
# The result is clamped to sunrise_epoch (solar ceiling) so the window
# never extends into daytime, regardless of when moonset occurs.
#
# Arguments:
#   $1 - MOON_PHASE_WINDOW_DURATION value (number or "moonset")
#   $2 - window_start epoch
#   $3 - lunar_window_end: an inferred-or-actual moonset epoch, never zero.
#        Callers must guarantee this via get_effective_lunar_window →
#        infer_lunar_window_bounds before invoking this function.
#        Midnight fallback is NOT this function's responsibility.
#   $4 - sunrise_epoch (0 if unavailable; used to enforce solar ceiling)
# Outputs:
#   Window end epoch
#######################################
resolve_window_end() {
	local param="$1" window_start="$2" moonset="$3" sunrise="${4:-0}"
	local end

	if [[ "$param" == "moonset" ]]; then
		end="$moonset"
	else
		end=$(( window_start + ${param:-60} * 60 ))
	fi

	echo "$end"
}

#######################################
# Infer the lunar window bounds when rise/set data is incomplete.
#
# Fallback Logic:
#   If moonset_epoch == 0 (missing/invalid):
#       Inferred window: moonrise_epoch → moonrise_epoch + 12h 25m
#   If moonrise_epoch == 0 (missing/invalid):
#       Inferred window: moonset_epoch - 12h 25m → moonset_epoch
#   If both are valid (non-zero):
#       Return actual data (no inference needed)
#
# Note:
#   The 12h 25m window (44700 seconds) is a standard astronomical lunar
#   visibility duration, used when actual rise/set times are unavailable.
#
# Arguments:
#   $1 - moonrise_epoch (0 if unavailable)
#   $2 - moonset_epoch  (0 if unavailable)
# Outputs:
#   Tab-separated: inferred_start_epoch<TAB>inferred_end_epoch<TAB>has_fallback_flag
#   has_fallback_flag is "true" if ANY inference applied; "false" if using actual data
# Returns:
#   0 always
#######################################
infer_lunar_window_bounds() {
	local moonrise_epoch="$1"
	local moonset_epoch="$2"

	# Standard lunar visibility window in seconds: 12h 25m
	local LUNAR_WINDOW_DURATION=44700

	local inferred_start inferred_end has_fallback

	# Case 1: Both valid — use actual data
	if (( moonrise_epoch > 0 && moonset_epoch > 0 )); then
		inferred_start="$moonrise_epoch"
		inferred_end="$moonset_epoch"
		has_fallback="false"
	# Case 2: Only moonrise is valid — infer from moonrise
	elif (( moonrise_epoch > 0 )); then
		inferred_start="$moonrise_epoch"
		inferred_end=$(( moonrise_epoch + LUNAR_WINDOW_DURATION ))
		has_fallback="true"
	# Case 3: Only moonset is valid — infer from moonset
	elif (( moonset_epoch > 0 )); then
		inferred_start=$(( moonset_epoch - LUNAR_WINDOW_DURATION ))
		inferred_end="$moonset_epoch"
		has_fallback="true"
	# Case 4: Neither valid — return zeros
	else
		inferred_start=0
		inferred_end=0
		has_fallback="false"
	fi

	printf "%s\t%s\t%s\n" "$inferred_start" "$inferred_end" "$has_fallback"
}

#######################################
# Determine the effective lunar window: either actual or inferred.
#
# For most purposes (cache staleness, moon phase display), this returns
# the best available lunar window. For announcements (moonrise/moonset),
# call parse_moon_times directly to enforce strict API-data-only rule.
#
# Arguments:
#   $1 - moonrise_epoch (from API; 0 if unknown)
#   $2 - moonset_epoch  (from API; 0 if unknown)
# Outputs:
#   Tab-separated: window_start<TAB>window_end
# Returns:
#   0 always
#######################################
get_effective_lunar_window() {
	local moonrise_epoch="$1"
	local moonset_epoch="$2"

	local inferred_start inferred_end has_fallback
	IFS=$'\t' read -r inferred_start inferred_end has_fallback \
		<<<"$(infer_lunar_window_bounds "$moonrise_epoch" "$moonset_epoch")"

	printf "%s\t%s\n" "$inferred_start" "$inferred_end"
}

#######################################
# Determine whether to show moon phase and return the formatted string.
#
# Shows moon if ALL conditions are met:
# 1. MOON_PHASE_ENABLED is true (master kill switch)
# 2. Current time is between effective sunset and sunrise (solar window)
# 3. Moon is visible (within effective lunar window, actual or inferred)
# 4. Current time is within display window (configured start/end)
# 5. Not suppressed by rain conditions
# 6. Not suppressed by SUPPRESS_NOT_VISIBLE_MOONPHASE (if enabled)
#
# Lunar Window Strategy:
# The effective lunar window is:
#   - The actual [moonrise, moonset] if both API values are valid (non-zero)
#   - Otherwise, an inferred 12h 25m window based on whichever value exists
#   - Never suppressed due to incomplete rise/set data
#
# Window Calculation:
# Solar Window: effective_sunset_epoch (Day N) → effective_sunrise_epoch (Day N+1)
# Lunar Window: Effective window (actual or inferred via get_effective_lunar_window)
# Final Window: intersection of solar and lunar, further refined by user-configured display window
#   window_start = max(effective_sunset, lunar_window_start) + MOON_PHASE_WINDOW_START minutes
#   window_end   = clamped to effective_sunrise by resolve_window_end (solar ceiling)
#
# Time Comparison: All comparisons use Unix epoch (seconds), eliminating
# "crossing midnight" issues that would arise from HH:MM string comparisons.
#
# Globals:
#   MOON_PHASE_ENABLED, MOON_PHASE_WINDOW_START, MOON_PHASE_WINDOW_DURATION,
#   SHOW_MOON_PHASE_DURING_RAIN, SHOW_MOON_PHASE_WITH_RAIN_FORECAST,
#   SUPPRESS_NOT_VISIBLE_MOONPHASE, SHOW_MOONPHASE_DURING_DAYTIME
# Arguments:
#   $1 - effective_sunset_epoch  (yesterday's if overnight, today's otherwise)
#   $2 - effective_sunrise_epoch (tomorrow's if past today's sunrise)
#   $3 - is_currently_raining (default: false)
#   $4 - has_rain_forecast (default: false)
#   $5 - Moon data JSON string (required for phase display)
# Outputs:
#   Formatted moon phase string, or nothing if conditions not met
# Returns:
#   0 always
#######################################
resolve_moon_phase() {
	local effective_sunset_epoch="$1"
	local effective_sunrise_epoch="${2:-0}"
	local is_currently_raining="${3:-false}"
	local has_rain_forecast="${4:-false}"
	local moon_data="${5:-}"

	# 1. Check master toggle
	if [[ "$MOON_PHASE_ENABLED" != "true" ]]; then
		return 0
	fi

	# 2. Validate moon data exists and is valid
	if [[ -z "$moon_data" ]] || ! is_valid_moon_data "$moon_data"; then
		return 0
	fi

	# 3. Resolve moon times (moonrise/moonset from API)
	local moonrise_epoch moonset_epoch
	IFS=$'\t' read -r moonrise_epoch moonset_epoch \
		<<<"$(parse_moon_times "$moon_data" "$effective_sunrise_epoch")"

	# 4. Check solar window (effective_sunset → effective_sunrise, crossing midnight)
	local now
	now=$(date +%s)

	# Skip solar window restriction if show phase during daytime is enabled.
	if [[ "$SHOW_MOONPHASE_DURING_DAYTIME" != "true" ]]; then
		# Solar window is active if:
		#   now >= effective_sunset_epoch AND now < effective_sunrise_epoch
		# This naturally handles crossing midnight because:
		#   - Before midnight: effective_sunset < midnight < effective_sunrise (next day)
		#   - After midnight:  yesterday's effective_sunset < now < today's effective_sunrise
		if ! (( now >= effective_sunset_epoch && now < effective_sunrise_epoch )); then
			# Not in solar window (daytime) — suppress moon phase
			return 0
		fi
	fi

	# 5. Get effective lunar window (actual or inferred from partial API data)
	# Uses 12h 25m fallback window if either moonrise or moonset is 0.
	# This ensures moon phase display even with incomplete rise/set data.
	local lunar_window_start lunar_window_end
	IFS=$'\t' read -r lunar_window_start lunar_window_end \
		<<<"$(get_effective_lunar_window "$moonrise_epoch" "$moonset_epoch")"

	# Cannot proceed without valid lunar window
	(( lunar_window_start > 0 && lunar_window_end > 0 )) || return 0

	# 6. Check if current time is within lunar window
	# (actual or inferred from partial data)
	if ! (( now >= lunar_window_start && now < lunar_window_end )); then
		# Outside lunar window — suppress moon phase
		return 0
	fi

	# 7. Handle day-boundary edge case:
	# If actual moonrise exists but moonset was inferred, ensure moonset > moonrise
	# (similarly, if moonset exists but moonrise was inferred).
	# The infer function already handles this, but validate window consistency.
	if (( lunar_window_end <= lunar_window_start )); then
		return 0  # Invalid window detected — suppress
	fi

	# 8. Resolve display window (user-configured start/end)
	# lunar_window_start is passed as the moonrise anchor so that resolve_window_start
	# always receives a valid epoch — real moonrise when available, or the value
	# already inferred by infer_lunar_window_bounds (moonset - 12h 25m) when not.
	# This keeps all inference logic in one place (DRY).
	local window_start window_end
	window_start=$(resolve_window_start \
		"$MOON_PHASE_WINDOW_START" \
		"$effective_sunset_epoch" \
		"$lunar_window_start" \
		"$SHOW_MOONPHASE_DURING_DAYTIME")
	window_end=$(resolve_window_end "$MOON_PHASE_WINDOW_DURATION" "$window_start" "$lunar_window_end" "$effective_sunrise_epoch")

	# 9. Check if current time is within display window
	if ! (( now >= window_start && now < window_end )); then
		# Outside display window — suppress moon phase
		return 0
	fi

	# 10. Check rain suppression (after all other conditions pass)
	if [[ "$is_currently_raining" == "true" ]] && [[ "$SHOW_MOON_PHASE_DURING_RAIN" != "true" ]]; then
		# Currently raining and suppression enabled — suppress moon phase
		return 0
	fi

	if [[ "$has_rain_forecast" == "true" ]] && [[ "$SHOW_MOON_PHASE_WITH_RAIN_FORECAST" != "true" ]] && [[ "$SHOW_RAIN_FORECAST" == "true" ]]; then
		# Rain forecasted and suppression enabled — suppress moon phase
		return 0
	fi

	# 11. Suppress moon phase if moon is not visible (day or night).
	if [[ "$SUPPRESS_NOT_VISIBLE_MOONPHASE" == "true" ]]; then
		local illumination_pct
		illumination_pct=$(parse_illumination_pct "$moon_data")

		if is_moon_too_dim "$illumination_pct"; then
			return 0  # suppress output (moon not visible)
		fi
	fi

	# 12. All conditions met — resolve and display moon phase
	local phase_index
	phase_index=$(resolve_phase_index "$moon_data")

	if [[ -n "$phase_index" ]]; then
		local syzygy_label
		# Pass already-resolved moon times (actual API values), effective_sunset_epoch,
		# and effective_sunrise_epoch so the night-visibility gate inside
		# get_lunar_apsidal_syzygy needs no extra parsing.
		# Note: moonrise_epoch and moonset_epoch are actual API values
		# (may be 0), used only for apsidal event decision, not announcements.
		syzygy_label=$(get_lunar_apsidal_syzygy \
			"$moon_data" \
			"$moonrise_epoch" \
			"$moonset_epoch" \
			"$effective_sunset_epoch" \
			"$effective_sunrise_epoch")
		get_moon_phase "$phase_index" "$syzygy_label" "$moon_data"
	fi
}

#######################################
# Calculate minutes until an event epoch
# Arguments:
#   $1 - Event epoch time
# Outputs:
#   Integer minutes until event (negative if past)
#######################################
minutes_until_event() {
	local event_epoch="$1"
	local current_epoch
	current_epoch=$(date +%s)
	echo $(((event_epoch - current_epoch) / 60))
}

#######################################
# Build and return the formatted weather display line.
# Composes temperature, feels-like, sunrise/sunset warnings,
# rain warning, and moon phase into a single output string.
#
# Arguments:
#   $1 - Weather description
#   $2 - Icon emoji
#   $3 - Temperature
#   $4 - Feels-like temperature
#   $5 - Sunrise epoch
#   $6 - Sunset epoch
#   $7 - Rain warning string (optional)
#   $8 - is_currently_raining flag (true/false, optional, default: false)
#   $9 - has_rain_forecast flag (true/false, optional, default: false)
#   $10 - Moon data JSON string (optional)
# Outputs:
#   Formatted weather line string
#######################################
build_weather_line() {
	local desc="$1"
	local icon="$2"
	local temp="$3"
	local feels_like="$4"
	local sunrise_epoch="${5:-0}"
	local sunset_epoch="${6:-0}"
	local rain_warning="${7:-}"
	local is_currently_raining="${8:-false}"
	local has_rain_forecast="${9:-false}"
	local moon_data="${10:-}"
	local effective_sunset_epoch="${11:-$sunset_epoch}"
	local effective_sunrise_epoch="${12:-$sunrise_epoch}"

	local line="       ${icon}  ${desc}  ${temp}°C"

	# Append feels-like if the difference exceeds FEELS_LIKE_THRESHOLD
	# Can be disabled by setting FEELS_LIKE_THRESHOLD=disable
	if [[ "$FEELS_LIKE_THRESHOLD" != "disable" ]]; then
		local diff
		diff=$(awk -v t="$temp" -v f="$feels_like" 'BEGIN { d = t - f; print (d < 0 ? -d : d) }')
		if awk -v diff="$diff" -v threshold="$FEELS_LIKE_THRESHOLD" 'BEGIN { exit !(diff > threshold) }'; then
			local formatted_feels_like
			formatted_feels_like=$(format_temperature "$feels_like")
			line="       ${icon}  ${desc}  ${temp}°C  (Feels ${formatted_feels_like}°C)"
		fi
	fi

	if [[ "$SHOW_SUNRISE_SUNSET" == "true" ]]; then
		if [[ "$is_currently_raining" == "true" ]] && [[ "$SHOW_SUNRISE_SUNSET_DURING_RAIN" != "true" ]]; then
			:
		elif [[ "$has_rain_forecast" == "true" ]] && [[ "$SHOW_SUNRISE_SUNSET_WITH_RAIN_FORECAST" != "true" ]] && [[ "$SHOW_RAIN_FORECAST" == "true" ]]; then
			:
		else
			local minutes

		# Add sunrise info if within threshold
		if [[ $sunrise_epoch -gt 0 ]]; then
			minutes=$(minutes_until_event "$sunrise_epoch")
			if ((minutes > 0 && minutes <= SUNRISE_WARNING_THRESHOLD)); then
				local sunrise_time
				sunrise_time=$(format_time "$sunrise_epoch")
				line+="    Sunrise: ${sunrise_time^^}"
			fi
		fi

		# Add sunset info if within threshold (use effective_sunset for overnight accuracy)
		if [[ $effective_sunset_epoch -gt 0 ]]; then
			minutes=$(minutes_until_event "$effective_sunset_epoch")

			if ((minutes > 0 && minutes <= SUNSET_WARNING_THRESHOLD)); then
				local sunset_time
				sunset_time=$(format_time "$effective_sunset_epoch")
				line+="    Sunset: ${sunset_time^^}"
			fi
		fi
		fi
	fi

	if [[ "$SHOW_RAIN_FORECAST" == "true" ]]; then

		# Rain warning
		if [[ -n "$rain_warning" ]]; then
			line+="    ${rain_warning}"
		fi
	fi
	
	# Moon phase
	local moon_phase
	moon_phase=$(resolve_moon_phase "$effective_sunset_epoch" "$effective_sunrise_epoch" "$is_currently_raining" "$has_rain_forecast" "$moon_data")
	if [[ -n "$moon_phase" ]]; then
		line+="    ${moon_phase}"
	fi

	# Hoisted parsing, shared by moonrise + moonset warning
	local _moonrise_epoch=0 _moonset_epoch=0
	if [[ -n "$moon_data" ]]; then
		IFS=$'\t' read -r _moonrise_epoch _moonset_epoch \
			<<<"$(parse_moon_times "$moon_data" "$effective_sunrise_epoch")"
	fi

	# Master toggle for all moon events
	if [[ "$SHOW_MOONRISE_MOONSET" == "true" ]]; then

		# Rain suppression (reuse moon phase logic)
		if [[ "$is_currently_raining" == "true" ]] && [[ "$SHOW_MOONRISE_MOONSET_DURING_RAIN" != "true" ]]; then
			:
		elif [[ "$has_rain_forecast" == "true" ]] && [[ "$SHOW_MOONRISE_MOONSET_WITH_RAIN_FORECAST" != "true" ]] && [[ "$SHOW_RAIN_FORECAST" == "true" ]]; then
			:
		else

			local now
			now=$(date +%s)
			
			local is_daytime=false
			if (( now >= sunrise_epoch && now < effective_sunset_epoch )); then
				is_daytime=true
			fi

			# Suppress moonrise/moonset when moon is too dim to be visible,
			local _suppress_moonrise_moonset=false
			if [[ "$SUPPRESS_NOT_VISIBLE_MOONRISE_MOONSET" == "true" ]] && [[ -n "$moon_data" ]]; then
				local _illumination_pct
				_illumination_pct=$(parse_illumination_pct "$moon_data")
				if is_moon_too_dim "$_illumination_pct"; then
					_suppress_moonrise_moonset=true
				fi
			fi

			# Moonrise announcement
			if [[ "$_suppress_moonrise_moonset" != "true" ]] && (( _moonrise_epoch > 0 && now < _moonrise_epoch)); then
				if [[ "$is_daytime" == "true" ]] && [[ "$SHOW_MOONRISE_MOONSET_DURING_DAYTIME" != "true" ]]; then
					:
				elif [[ "$MOONRISE_WARNING_THRESHOLD" == "sunset" ]]; then
					# Only show moonrise if it's after sunset
					if (( now >= effective_sunset_epoch && _moonrise_epoch > effective_sunset_epoch )); then
						local moonrise_time
						moonrise_time=$(format_time "$_moonrise_epoch")
						line+="    Moonrise: ${moonrise_time^^}"
					fi
				else
					# Numeric threshold: existing behavior
					local mins_to_moonrise
					mins_to_moonrise=$(minutes_until_event "$_moonrise_epoch")
					if (( mins_to_moonrise > 0 && mins_to_moonrise <= MOONRISE_WARNING_THRESHOLD )); then
						local moonrise_time
						moonrise_time=$(format_time "$_moonrise_epoch")
						line+="    Moonrise: ${moonrise_time^^}"
					fi
				fi
			fi

			# Moonset announcement
			if [[ "$_suppress_moonrise_moonset" != "true" ]] && (( _moonset_epoch > 0 && now < _moonset_epoch )); then
				if [[ "$is_daytime" == "true" ]] && [[ "$SHOW_MOONRISE_MOONSET_DURING_DAYTIME" != "true" ]]; then
					:
				else
					if [[ "$MOONSET_WARNING_THRESHOLD" == "sunset" ]]; then
						# Only show moonset if it's after sunset
						if (( now >= effective_sunset_epoch && _moonset_epoch > effective_sunset_epoch )); then
							local moonset_time
							moonset_time=$(format_time "$_moonset_epoch")
							line+="    Moonset: ${moonset_time^^}"
						fi
					else
						# Numeric threshold: existing behavior
						local mins_to_moonset
						mins_to_moonset=$(minutes_until_event "$_moonset_epoch")

						if (( mins_to_moonset > 0 && mins_to_moonset <= MOONSET_WARNING_THRESHOLD )); then
							local moonset_time
							moonset_time=$(format_time "$_moonset_epoch")
							line+="    Moonset: ${moonset_time^^}"
						fi
					fi
				fi
			fi
		fi
	fi

	# Use wc -m for accurate Unicode character count (${#line} overcounts emoji)
	local line_len
	line_len=$(printf '%s' "$line" | wc -m)
	local MAX_LINE_LEN=90

	# If final line exceeds MAX_LINE_LEN characters, shorten rain_warning to show only emoji and time/probability
	# (but not when outputting JSON, as the full info is needed)

	if (( line_len >= MAX_LINE_LEN )) && [[ -n "$rain_warning" ]] && [[ "${EMIT_JSON_OUTPUT:-false}" != "true" ]]; then
		# Extract emoji from rain_warning and keep only time/probability info
		# Format: 🌧️  Rain likely ≈ 12:00 PM (80%)
		# Result: 🌧️  ≈ 12:00 PM (80%)
		local shortened_rain_warning
		shortened_rain_warning=$(sed -E "s/^([^ ]*)  .*≈(.*)$/\1  ≈\2/" <<<"$rain_warning")

		# Rebuild the line with shortened rain_warning
		line="${line//"    ${rain_warning}"/"    ${shortened_rain_warning}"}"
		line_len=$(printf '%s' "$line" | wc -m)
	fi

	# If line still exceeds MAX_LINE_LEN characters and moon_phase is present, strip its description
	# leaving only the moon phase emoji (e.g. "🌕  Waxing Gibbous" → "🌕")
	# (but not when outputting JSON, as the full info is needed)

	if (( line_len >= MAX_LINE_LEN )) && [[ -n "$moon_phase" ]] && [[ "${EMIT_JSON_OUTPUT:-false}" != "true" ]]; then
		# moon_phase format: "<emoji>  <description...>"  (two spaces after emoji)
		# Extract just the leading emoji (everything before the first two-space gap)
		local moon_phase_emoji
		moon_phase_emoji=$(sed -E "s/^([^ ]+)  .*$/\1/" <<<"$moon_phase")

		# Replace the full moon_phase segment in the line with the emoji-only version
		line="${line//"    ${moon_phase}"/"    ${moon_phase_emoji}"}"
	fi

	echo "$line"
}

#######################################
# Main function
#######################################
main() {
	# Check connectivity
	if ! check_connectivity; then
		exit 1
	fi

	# Fetch weather data
	local response
	if ! response=$(fetch_weather_data); then
		echo "               Weather data unavailable" >&2
		exit 1
	fi

	# Parse weather data
	local weather_main desc icon temp feels_like sunrise_epoch sunset_epoch

	IFS=$'\t' read -r weather_main desc icon temp feels_like sunrise_epoch sunset_epoch <<< \
    "$(parse_weather_data "$response")"

	# Validate parsed data
	if [[ -z "$desc" ]]; then
		echo "               Weather data unavailable" >&2
		exit 1
	fi

	# Save today's sun data for overnight use tomorrow
	save_sun_data "$sunrise_epoch" "$sunset_epoch"

	# Resolve effective sunset (yesterday's if overnight)
	local effective_sunset_epoch
	effective_sunset_epoch=$(get_effective_sunset "$sunset_epoch" "$sunrise_epoch")

	# Resolve effective sunrise (tomorrow's if we're past today's sunrise)
	local effective_sunrise_epoch
	effective_sunrise_epoch=$(get_effective_sunrise "$sunrise_epoch")

	# Format data
	local weather_desc icon_emoji formatted_temp
	weather_desc=$(capitalize_words "$desc")
	icon_emoji=$(get_weather_icon "$icon")
	formatted_temp=$(format_temperature "$temp")

	local forecast_response=""  # initialized empty — may remain unset if fetch fails
	local rain_data rain_warning=""
    if forecast_response=$(fetch_forecast_data); then
        if rain_data=$(get_rain_forecast "$forecast_response"); then
            if [[ -n "$rain_data" ]]; then
    			local rain_epoch rain_prob rain_desc rain_icon rain_icon_emoji
    			IFS=$'\t' read -r rain_epoch rain_prob rain_desc rain_icon <<<"$rain_data"
				rain_icon_emoji=$(get_weather_icon "$rain_icon")
    			rain_warning=$(format_rain_warning "$rain_epoch" "$rain_prob" "$rain_desc" "$rain_icon_emoji")
			fi
        fi
    fi

	# Determine rain status — distinguish between current and forecast
	local is_currently_raining=false
	local has_rain_forecast=false
	
	# Current rain check (from weather_main) — OWM returns Title Case
	if [[ "${weather_main,,}" =~ ^(rain|drizzle|thunderstorm)$ ]]; then
		is_currently_raining=true
	fi
	
	# Forecast rain check (from rain_warning)
	if [[ -n "$rain_warning" ]]; then
		has_rain_forecast=true
	fi

	# Fetch moon data (with caching and graceful degradation)
	local moon_data=""
	if [[ "$MOON_PHASE_ENABLED" == "true" ]]; then
		moon_data=$(get_moon_data) || moon_data=""
	fi

	# Build output
	local weather_line
	# Change signature to accept effective_sunset separately, or handle inside main:
	weather_line=$(build_weather_line \
		"$weather_desc" \
		"$icon_emoji" \
		"$formatted_temp" \
		"$feels_like" \
		"$sunrise_epoch" \
		"$sunset_epoch" \
		"$rain_warning" \
		"$is_currently_raining" \
		"$has_rain_forecast" \
		"$moon_data" \
		"$effective_sunset_epoch" \
		"$effective_sunrise_epoch")

	# Output based on caller mode
	if [[ "${EMIT_JSON_OUTPUT:-false}" == "true" ]]; then
		echo "$weather_line"
		echo "---END-WEATHER-LINE---"

        # Only emit combined JSON if forecast data is available
        if [[ -n "$forecast_response" ]]; then
            local combined_json
            combined_json=$(jq -n \
                --argjson weather "$response" \
                --argjson forecast "$forecast_response" \
                '{weather: $weather, forecast: $forecast}')
            echo "$combined_json"
        else
            jq -n --argjson weather "$response" '{weather: $weather}' 
        fi
	else
		echo "$weather_line"
	fi
}

# Run main function
main "$@"