"""Generate a 499-A engagement letter for past-due/multi-year refiling.

Produces a DOCX engagement letter that the client must eSign before
we begin work on revised 499-A filings for prior years.
"""
from __future__ import annotations

import os
from datetime import date
from typing import Optional


def generate_engagement_letter(
    *,
    entity_name: str,
    frn: str = "",
    contact_name: str = "",
    contact_email: str = "",
    filing_years: list[int] | None = None,
    fee_description: str = "",
    order_number: str = "",
    output_path: str,
) -> str:
    """Generate the engagement letter DOCX. Returns the output path."""
    from docx import Document
    from docx.shared import Pt, Inches, RGBColor
    from docx.enum.text import WD_ALIGN_PARAGRAPH

    NAVY = RGBColor(0x1A, 0x27, 0x44)
    GREEN = RGBColor(0x05, 0x96, 0x69)
    today = date.today()
    today_str = today.strftime("%B %d, %Y")
    years_str = ", ".join(str(y) for y in (filing_years or [today.year]))

    doc = Document()
    for s in doc.sections:
        s.top_margin = Inches(1)
        s.bottom_margin = Inches(1)
        s.left_margin = Inches(1.25)
        s.right_margin = Inches(1.25)

    # Header
    tp = doc.add_paragraph()
    tp.alignment = WD_ALIGN_PARAGRAPH.CENTER
    tr = tp.add_run("Engagement Letter")
    tr.font.size = Pt(16)
    tr.bold = True
    tr.font.color.rgb = NAVY

    sp = doc.add_paragraph()
    sp.alignment = WD_ALIGN_PARAGRAPH.CENTER
    sr = sp.add_run("FCC Form 499-A Revenue Audit & Revised Filing")
    sr.font.size = Pt(11)
    sr.italic = True
    sp.paragraph_format.space_after = Pt(16)

    def _p(text: str, bold: bool = False, size: int = 11) -> None:
        p = doc.add_paragraph()
        p.paragraph_format.space_after = Pt(6)
        r = p.add_run(text)
        r.font.size = Pt(size)
        r.bold = bold

    def _h(text: str) -> None:
        p = doc.add_paragraph()
        p.paragraph_format.space_before = Pt(12)
        p.paragraph_format.space_after = Pt(4)
        r = p.add_run(text)
        r.font.size = Pt(12)
        r.bold = True
        r.font.color.rgb = NAVY

    _p(f"Date: {today_str}")
    _p(f"Client: {entity_name}", bold=True)
    if frn:
        _p(f"FCC Registration Number (FRN): {frn}")
    if contact_name:
        _p(f"Contact: {contact_name}" + (f" ({contact_email})" if contact_email else ""))
    if order_number:
        _p(f"Order Reference: {order_number}")

    _h("1. Scope of Services")
    _p(
        f"Performance West Inc. (\"PW\") will provide the following compliance "
        f"consulting services for {entity_name} (\"Client\"):"
    )
    _p(
        f"  a) Revenue audit of Client's FCC Form 499-A filings for calendar "
        f"year(s) {years_str} to identify potential revenue misclassifications "
        f"affecting the Universal Service Fund (USF) contribution base."
    )
    _p(
        f"  b) Preparation and submission of revised FCC Form 499-A filings "
        f"for the identified calendar year(s) with corrected revenue classifications."
    )
    _p(
        f"  c) Evaluation of Client's eligibility for de minimis exemption "
        f"under 47 CFR \u00a7 54.708."
    )
    _p(
        f"  d) Assistance with USAC billing dispute documentation and "
        f"payment plan applications, if applicable."
    )

    _h("2. Fee Structure")
    if fee_description:
        _p(fee_description)
    else:
        _p(
            f"PW's fee for these services is $499 per calendar year of revised "
            f"filing, totaling ${499 * len(filing_years or [today.year])} for "
            f"{len(filing_years or [today.year])} year(s)."
        )
    _p(
        "Payment is due upon engagement. This fee covers the revenue audit, "
        "revised form preparation, and submission. Government filing fees, "
        "if any, are the Client's responsibility and will be disclosed "
        "before submission."
    )

    _h("3. Authorization")
    _p(
        f"Client hereby authorizes PW to prepare and submit revised FCC "
        f"Form 499-A filings on Client's behalf for the calendar year(s) "
        f"identified above. Client understands that PW will submit these "
        f"forms to the Universal Service Administrative Company (USAC) "
        f"using the Client's Filer ID and FRN."
    )

    _h("4. Not Legal Advice")
    _p(
        "PW is a compliance consulting firm, not a law firm. The services "
        "described in this letter constitute regulatory form preparation "
        "and compliance consulting, not legal advice or legal representation. "
        "PW does not provide legal opinions, represent clients before the "
        "FCC in adjudicatory proceedings, or create an attorney-client "
        "relationship."
    )
    _p(
        "If Client requires legal representation before the FCC (e.g., "
        "appeals under 47 CFR \u00a7 54.719, waiver requests, or enforcement "
        "proceedings), PW will refer Client to a qualified telecommunications "
        "attorney."
    )

    _h("5. Client Responsibilities")
    _p(
        "Client certifies that all information provided to PW is accurate "
        "and complete to the best of Client's knowledge. Client understands "
        "that FCC Form 499-A filings carry a certification of accuracy and "
        "that false statements may result in penalties under 18 U.S.C. \u00a7 1001."
    )
    _p(
        "Client agrees to provide PW with access to revenue records, "
        "financial statements, and other documentation reasonably necessary "
        "to perform the revenue audit and prepare revised filings."
    )

    _h("6. Limitation of Liability")
    _p(
        "PW's liability under this engagement is limited to the fees paid "
        "by Client for the services described herein. PW is not responsible "
        "for penalties, interest, or other charges assessed by USAC or the "
        "FCC, whether arising from prior filings, revised filings, or any "
        "other cause."
    )

    _h("7. Term")
    _p(
        "This engagement begins upon signature below and continues until "
        "the revised filings have been submitted to USAC, or until "
        "terminated by either party with written notice."
    )

    # Signature block
    doc.add_paragraph()
    _p("AGREED AND ACCEPTED:", bold=True)
    doc.add_paragraph()

    _p(f"Client: {entity_name}")
    _p("Signature: ____________________________________")
    _p("Name: ____________________________________")
    _p("Title: ____________________________________")
    _p(f"Date: {today_str}")

    doc.add_paragraph()

    _p("Performance West Inc.")
    _p("525 Randall Ave Ste 100-1195, Cheyenne, WY 82001")
    _p("1-888-411-0383 | info@performancewest.net")

    doc.save(output_path)
    return output_path