"""Strict parsing for record-ID pagination cursors."""

from app.core.errors import InvalidCursorError

MAX_CURSOR_VALUE = 2**63 - 1


def parse_cursor(raw: str | None, *, field: str = "cursor") -> int | None:
    if raw is None or not raw.strip():
        return None
    value = raw.strip()
    if not value.isascii() or not value.isdigit():
        raise InvalidCursorError(f"{field} must be an ASCII decimal record ID")
    parsed = int(value)
    if parsed < 1 or parsed > MAX_CURSOR_VALUE:
        raise InvalidCursorError(f"{field} is outside the record ID range")
    return parsed