import math
from datetime import datetime, timezone
from typing import Any


def _ts() -> str:
    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")


def api_response(
    data: Any,
    message: str = "OK",
    status_code: int = 200,
) -> dict:
    """Standard JSON envelope: {data, message, statusCode, timestamp}."""
    return {
        "data": data,
        "message": message,
        "statusCode": status_code,
        "timestamp": _ts(),
    }


def page_response(
    items: list,
    total: int,
    page: int,
    size: int,
    message: str = "OK",
) -> dict:
    """Paginated response using Flutter contract keys.

    Input `page` can be 0-based (legacy internals) or 1-based.
    Output `data.page` is always 1-based.
    """
    total_pages = math.ceil(total / size) if size > 0 else 0
    normalized_page = page + 1 if page >= 0 else 1
    return {
        "data": {
            "items": items,
            "total": total,
            "page": normalized_page,
            "size": size,
            "pages": total_pages,
        },
        "message": message,
        "statusCode": 200,
        "timestamp": _ts(),
    }


def normalize_page_param(page: int) -> int:
    """Accept 0-based and 1-based page values; return a 0-based page index.

    This keeps backward compatibility with existing callers and Flutter clients
    that send `page=1` for the first page.
    """
    if page <= 1:
        return 0
    return page - 1