"""PDF utilities for YiSaiQi contract drafting."""
from __future__ import annotations

from pathlib import Path


def ensure_merged_pdf(source_paths: list[str], output_path: str) -> str:
    """Return one PDF path, merging multiple source PDFs when needed.

    YiSaiQi must upload only one YYC contract document for the same supplier
    and same order date. A single source PDF can be uploaded directly.
    """
    if not source_paths:
        raise ValueError("YYC contract creation requires at least one platform PDF")
    if len(source_paths) == 1:
        return source_paths[0]

    try:
        from pypdf import PdfWriter
    except ImportError as exc:
        raise RuntimeError("Install pypdf to merge multiple YYC platform PDFs") from exc

    writer = PdfWriter()
    for source in source_paths:
        writer.append(str(Path(source)))

    out = Path(output_path)
    out.parent.mkdir(parents=True, exist_ok=True)
    with out.open("wb") as file:
        writer.write(file)
    return str(out)