import uuid from datetime import datetime, timezone def generate_uuid() -> str: """Generate a new UUID4 string.""" return str(uuid.uuid4()) def utcnow() -> datetime: """Return current UTC datetime (timezone-aware).""" return datetime.now(timezone.utc) def build_success_response(data: dict | list, message: str = "Success") -> dict: """Build a standard API success response envelope.""" return {"success": True, "data": data, "message": message} def build_error_response(code: str, message: str, details: dict = {}) -> dict: """Build a standard API error response envelope.""" return { "success": False, "error": {"code": code, "message": message, "details": details}, } def paginate(items: list, page: int, page_size: int) -> dict: """Paginate a list of items and return pagination metadata.""" total = len(items) start = (page - 1) * page_size end = start + page_size return { "items": items[start:end], "total": total, "page": page, "page_size": page_size, "total_pages": (total + page_size - 1) // page_size, }