"""Text helpers shared across mail-parsing jobs."""
from __future__ import annotations

from typing import Optional


def sanitize_surrogates(value: Optional[str]) -> Optional[str]:
    """Strip surrogates a compat32 bytes-parse can leave in header text.

    Lone surrogates are not valid UTF-8 and postgres jsonb rejects them; each
    undecodable byte degrades to '?' instead. Real Unicode passes through.

    Shared by gmail-header-backfill (header text) and gmail-bulk-import
    (Message-ID → envelope id): both parse Gmail Takeout .eml bytes under
    compat32, where 8-bit header bytes surface as email.header.Header /
    surrogate-laden strings that must not reach json.dumps or jsonb.
    """
    if value is None:
        return None
    return value.encode("utf-8", errors="replace").decode("utf-8")
